🧱 Pulumi Error: 'The Stack's Checkpoint Is Corrupt' Snapshot Integrity

Exact Error Message

error: the stack's checkpoint is corrupt: snapshot integrity failure; refusing to use it:
    resource urn:pulumi:prod::app::aws:s3/bucket:Bucket::data refers to unknown provider
    urn:pulumi:prod::app::pulumi:providers:aws::default_6_0_0::04da6b54-...

You may also see snapshot integrity failure on pulumi up, pulumi refresh, or pulumi stack import, with variations such as resource ... refers to unknown resource (a dangling dependency) or duplicate resource ... in snapshot (two resources sharing a URN).

What It Means

Pulumi stores the desired-and-actual state of your stack in a JSON snapshot called the checkpoint. Before using it, the engine runs an integrity check: every resource must point at a provider that exists in the snapshot, every dependency URN must resolve, and URNs must be unique. When one of those invariants is broken, Pulumi refuses to proceed rather than risk deleting or duplicating live infrastructure.

The most common trigger is a hand-edited or partially-written state file: an interrupted operation, a merge of two state files, or a manual pulumi state delete that removed a provider still referenced by resources. The infrastructure itself is usually fine; the record of it is inconsistent.

Common Causes

• A resource references a provider URN that is missing from the snapshot (provider was deleted or renamed).
• A dependency or parent URN points at a resource no longer present in state.
• Two resources share the same URN (a bad manual merge or a botched rename).
• The checkpoint was hand-edited and left syntactically valid but semantically inconsistent.
• An interrupted pulumi up against a self-managed backend wrote a truncated snapshot.

Diagnostic Commands

Export the raw state so you can inspect exactly what the integrity check rejected:

pulumi stack export --show-secrets > stack.json

Find the offending resource or provider URN referenced in the error:

grep -n "default_6_0_0" stack.json

List which providers and resources the snapshot currently contains:

pulumi stack --show-urns

Re-run the failing operation with detail once you have a hypothesis:

pulumi preview --logtostderr -v=9 2>pulumi.log

Step-by-Step Resolution

1. Always start by exporting a backup you can restore:

pulumi stack export --show-secrets > stack-backup.json
cp stack-backup.json stack-fixed.json

2. Open stack-fixed.json and locate the resource named in the error. If it points at a missing provider, either restore that provider block or repoint the resource at an existing provider of the same type and version.

3. For a dangling dependency (a URN in dependencies or parent that no longer exists), remove the stale URN from the referencing resource’s entry, not the resource itself.

4. For a duplicate URN, rename or delete the erroneous copy so each URN appears exactly once in resources.

5. Re-import the corrected snapshot. pulumi stack import re-runs the integrity check, so it will reject the file again if anything is still inconsistent:

pulumi stack import --file stack-fixed.json

6. Reconcile state with reality using a read-only refresh before any mutating change:

pulumi refresh --preview-only
pulumi preview --diff

7. If a single resource is beyond repair and you can recreate it, delete just that entry from state and re-adopt it:

pulumi state delete 'urn:pulumi:prod::app::aws:s3/bucket:Bucket::data'
pulumi import aws:s3/bucket:Bucket data my-real-bucket-name

Prevention

• Never hand-edit the checkpoint in place; always go through pulumi stack export and pulumi stack import, which validate integrity on the way in.
• Use pulumi state delete --target-dependents carefully, and never delete a provider that resources still reference.
• On self-managed backends (S3/GCS/Azure blob), enable object versioning so an interrupted write leaves a recoverable prior snapshot.
• Avoid running two pulumi up operations against the same stack; rely on Pulumi’s per-stack lock rather than bypassing it.
• Keep an automated pulumi stack export in CI as a state backup before every deployment.
• Scaffold safe state-surgery steps from the Pulumi prompt library so export/import edits stay reversible.

Related Errors

• the stack is currently locked — a concurrent update, not a corrupt snapshot.
• the stack has pending operations — an interrupted update recorded in-flight ops; a different recovery path.
• could not decrypt configuration value — a secrets/passphrase problem, not integrity.
• resource ... refers to unknown resource — a dangling dependency, one specific form of this integrity failure.

Frequently Asked Questions

Is my actual cloud infrastructure damaged? Almost never. A corrupt checkpoint is a bookkeeping problem in Pulumi’s state file; your real resources are usually intact and are what a pulumi refresh will reconcile against.

Why does pulumi stack import reject my edited file too? Import runs the same integrity check as normal operations. If it still fails, your edit did not fully resolve the missing provider, dangling dependency, or duplicate URN.

Can I skip the integrity check to force it through? No, and you should not want to. The check exists precisely to stop Pulumi from deleting or duplicating live resources based on inconsistent state; bypassing it risks real data loss.

What is the safest first move? Run pulumi stack export --show-secrets > backup.json before touching anything. Every repair path is reversible as long as you have that untouched backup.

How do I avoid this on a team? Use a locking backend (Pulumi Cloud or a versioned object store), never edit state by hand, and export state in CI before each up. For more state and backend patterns, see the Pulumi guides.