Diagnostics

The stategraph diagnostics run command evaluates your root module's HCL locally and writes a detailed trace of how Stategraph reads it. During onboarding we ask new users to run this command and send us the output. The trace tells us exactly how your modules, variables, and file references evaluate on your machine, which lets us understand your setup and help you import cleanly on the first try.

This command makes no API calls. It runs only the local HCL evaluation, so you can run it before you have a server configured, an API key, or a single state imported. Nothing is uploaded. You run it, you get a file, and you decide what to send us.

Why we ask new users to run this

Every Terraform codebase is a little different: nested modules, for_each over computed values, file() and templatefile() reading data off disk, variables layered across .tfvars files. Before you import, we want to see how your specific HCL evaluates. The diagnostics trace gives us that picture without us needing access to your infrastructure, your cloud accounts, or your state.

Sending us this trace early means:

We can spot HCL patterns that need extra configuration (for example, files that need to be attached to an address) before they trip you up.
We can confirm your modules resolve the way you expect.
Support conversations start with data instead of back-and-forth screenshots.

What the trace contains (and what it does not)

The trace is a stream of greppable SG_TFEVAL_* lines describing the evaluation, followed by a one-line rollup summary. It records structure, not secrets: types, reasons, origins, reference addresses, and expressions rendered back to HCL source. It never records the contents of an evaluated value.

Data-map keys are hidden by default. That default keeps a run safe to share even when it is pointed at a production module. (Setting SG_DIAG_SHOW_KEYS=1 reveals those keys, but you do not need it for onboarding and should leave it off unless we ask.)

In short: the trace shows us how your HCL is shaped and how it evaluates, not the values it evaluates to.

Quickstart

Run it from your root module directory and write the trace to a file:

# From your Terraform root module
stategraph diagnostics run --out diagnostics.txt

Then send us diagnostics.txt. That is the whole onboarding step.

If your module needs variables to evaluate (most do), pass the same --var and --var-file flags you use with terraform plan:

stategraph diagnostics run \
  --out diagnostics.txt \
  --var-file prod.tfvars \
  --var region=us-east-1

To trace a module in another directory, pass it as the argument:

stategraph diagnostics run ./infra/networking --out networking-diagnostics.txt

Without --out, the trace streams to stderr instead, which is handy for a quick look:

stategraph diagnostics run 2>&1 | less

Options

stategraph diagnostics run [options] [DIR]

Arguments

Argument	Required	Description
`DIR`	No	Root module directory to evaluate. Defaults to the current directory.

Options

Option	Required	Description
`--out`	No	File to write the trace to. When omitted, the trace streams to stderr. For onboarding, always use `--out` so you have a file to send us.
`--workspace`	No	Workspace to evaluate (default: `default`, or set `STATEGRAPH_WORKSPACE`).
`--var`	No	Set a variable (`key=value`, repeatable).
`--var-file`	No	Path to a variable file (repeatable).
`--attach-files`	No	Attach files to resources matching an address glob (`ADDRESS_GLOB=FILE_GLOB`, repeatable). Only needed if we ask you to reproduce a file-attachment case.
`--attach-dest`	No	Destination directory for attached files (`ADDRESS_GLOB=DEST`, repeatable).

The diagnostics level is always verbose, so no level flag is needed. Verbose tracing emits one line per evaluated expression, so for a very large module the file can get big. That is expected, and the file compresses well if you want to zip it before sending.

Reading the output (optional)

You do not need to interpret the trace yourself, but here is what you are looking at if you are curious. Each line is a key=value record you can grep:

Line	What it reports
`SG_TFEVAL_ROOT`	The root module directory and workspace the run started from.
`SG_TFEVAL_NODE`	A resolved node (variable, local, output, module input) and its outcome.
`SG_TFEVAL_ATTR`	A resource attribute and whether it resolved, was unresolved, or was dropped.
`SG_TFEVAL_REF`	A reference between values and how its address resolved.
`SG_TFEVAL_FILE`	A `file()` / `templatefile()` / `fileset()` reference and any failure or warning.
`SG_TFEVAL_STEP`	One line per evaluated expression node (verbose detail).
`SG_TFEVAL_ROLLUP`	The end-of-run summary: counts of nodes, unresolved and dropped values, file failures, missing variables, coercions, and more.

A quick way to see the shape of a run is to read the last line:

grep SG_TFEVAL_ROLLUP diagnostics.txt

Or find anything that did not resolve cleanly:

grep 'outcome=dropped' diagnostics.txt
grep 'resolution=undefined' diagnostics.txt

The rollup alone often tells us most of what we need. If you want to sanity-check your own module before sending, non-zero node_dropped, file_failures, or vars_missing counts are the interesting ones.

What to send us

For onboarding, send the trace file:

stategraph diagnostics run --out diagnostics.txt --var-file prod.tfvars
# then attach diagnostics.txt to your onboarding thread

If you ran it against several root modules, send one file per module and name them so we can tell them apart. If a file is large, zip it first. Because the trace records structure rather than values, it is safe to share as-is, but you are always welcome to skim it first.

Next Steps

Import - Onboard a Terraform state and its HCL once diagnostics look clean
Velocity Setup - The end-to-end onboarding flow
HCL Commands - List addresses and evaluate expressions interactively
Troubleshooting - Common evaluation issues and fixes