pulumi/pulumi

Debugging

How to figure out why pulumi up is doing something unexpected.

Verbose CLI logging

Pulumi uses glog-style verbosity flags. The most useful incantations:

pulumi up -v=9 --logtostderr 2> /tmp/pulumi.log
pulumi up -v=11 --logflow --logtostderr 2> /tmp/pulumi.log

-v=9 is enough for most engine debugging.
-v=11 exposes very chatty plugin RPC logs.
--logflow propagates verbosity to plugins (language host, providers).
--logtostderr writes logs to stderr; otherwise they go to a temp file.

docs/debugging/ has a longer playbook.

Tracing

The CLI can produce OpenTelemetry traces:

pulumi up --tracing=file:./trace.zipkin
pulumi up --tracing=zipkin://localhost:9411

pkg/cmd/pulumi/trace/ and the cmdutil/cmdtrace helper handle the wiring.

Attaching a debugger

The engine supports being attached while running a deployment — the language host has explicit hooks for it. This is the canonical way to step through a user program under the engine's control.

pulumi up --attach-debugger

For attaching to the Go CLI itself:

mise exec -- dlv exec ./bin/pulumi -- up --yes

mise exec -- because Delve also lives under the mise-pinned tool versions.

For Node SDK debugging, the language host respects NODE_OPTIONS=--inspect-brk. For Python, set PULUMI_PYTHON_DEBUG=1 to enable debug-friendly behavior; see sdk/python/lib/pulumi/runtime/.

Plugin discovery and version pinning

Most "it works on my machine" issues are about plugin versions. Inspect what the engine sees:

pulumi plugin ls
pulumi plugin ls --project          # only what this project pins
ls ~/.pulumi/plugins/               # the on-disk cache

The plugin cache is at ~/.pulumi/plugins/ (PULUMI_PLUGINS_DIR overrides). A botched plugin install often clears up after rm -rf ~/.pulumi/plugins/<bad-plugin> (the only rm -rf that's safe under ~/.pulumi/; do not nuke the whole ~/.pulumi/).

The journal

Snapshots are written via a journal so a crash mid-update doesn't corrupt state. If a stack is in a weird state:

pulumi stack export > stack.json    # dump current snapshot
$EDITOR stack.json                  # surgical edits
pulumi stack import < stack.json    # write back

pulumi state delete <urn>           # higher-level surgery
pulumi state rename <oldurn> <newurn>
pulumi state move ...               # cross-stack

pkg/cmd/pulumi/state/ is the CLI surface; pkg/resource/edit/ is the underlying logic. The state file is not user-edited lightly — back it up, and prefer pulumi state subcommands to ad-hoc JSON edits.

Common errors and what they actually mean

Symptom	Likely cause
"language host failed to dial"	Wrong language host on PATH or version mismatch with SDK.
"could not load plugin ... no matching version"	Plugin cache mismatch. `pulumi plugin install resource <name>`.
"snapshot integrity error"	A previous run wrote a partial snapshot; export, fix, import.
"ResourceMonitor: ... transport is closing"	Engine cancelled the run; look earlier in the log.
Step generator panic	Real bug. Capture the seed and open an issue.

Reproducing CI failures locally

mise exec -- make test_fast
mise exec -- make test_all
./scripts/run-conformance.sh

If a specific job fails, look at .github/workflows/ci-run-test.yml to learn the exact command — they're not always plain make.