Skip to content

Inspecting State

What does alchemy think is deployed?

Section titled “What does alchemy think is deployed?”
Terminal window
bun alchemy state
AlchemyEffectWebsite
├─ dev_sam
│  ├─ Bucket
│  └─ Worker
└─ prod
 ├─ Bucket
 └─ Worker

In an interactive terminal, bare alchemy state opens the state explorer. It is a browsable tree of stacks, stages, and resources with a YAML preview of the selected state. This is the record used by the next plan, not the live cloud. See State Store. Full flag reference: state.

For scripts, drill down one level at a time with state list:

Terminal window
bun alchemy state list

Lists every stack in the store.

Terminal window
bun alchemy state list myapp

Lists every stage recorded under myapp.

Terminal window
bun alchemy state list myapp/dev_sam

Prints the state entries tracked under that stack and stage. Pass these paths to state read.

Or skip the drilling entirely and read the whole estate at once:

Terminal window
bun alchemy state read -r | jq 'to_entries[] | select(.value.resourceType == "AWS.EC2.Instance")'

One call returns every record across all stacks and stages as a single JSON document to filter locally — see state read.

Debugging a bad diff

Section titled “Debugging a bad diff”
Terminal window
bun alchemy state read myapp/dev_sam/Bucket

This is the persisted props/attrs the planner diffs against — see state for the output encoding. Compare it with what alchemy plan says it wants to change. Three usual causes:

Wrong stage. --stage defaults to live_$USER (e.g. live_sam), so a plan that “wants to create everything” often just means you’re looking at a stage you never deployed. Run state list myapp and confirm which stage actually has state.

Drift. The cloud changed out-of-band — someone edited the resource in a console or another tool. state read shows what alchemy last persisted; the reconciler converges observed cloud state to the desired state on the next deploy (see Resource Lifecycle).

Stale state from a partially-failed deploy. If a deploy crashed after mutating the cloud but before persisting, the record lags reality. Check the persisted attributes against what actually exists before reaching for state delete.

Recover from bad state

Section titled “Recover from bad state”

When the record is beyond repair, delete it and redeploy. state delete only deletes Alchemy’s local record. It does not delete cloud resources:

Terminal window
# one stage
bun alchemy state delete myapp/pr-42


# a whole stack
bun alchemy state delete myapp

Then deploy — resources alchemy owns are re-imported automatically:

Terminal window
bun alchemy deploy

If the deploy fails with OwnedBySomeoneElse, escalate:

Terminal window
bun alchemy deploy --adopt

See Adopting Resources for why the flag is usually unnecessary.

Orphaned local state

Section titled “Orphaned local state”

Pass --backend local to any state subcommand to read the on-disk .alchemy/state directory instead of the stack’s configured store. The canonical use: a Cloudflare state-store bootstrap was interrupted and left resources recorded only locally.

Terminal window
# wipe local state after a botched bootstrap
bun alchemy state delete myapp --backend local

See cloudflare for bootstrap repair.

Where next

Section titled “Where next”