🚨 Pulumi Error: 'snapshot integrity failure; refusing to use it' — Cause, Fix, and Troubleshooting Guide

Overview

error: snapshot integrity failure; refusing to use it means Pulumi loaded your stack’s state file (the snapshot) and its internal consistency checks failed before any operation ran. Pulumi verifies that every resource’s parent, provider, and dependencies references point to another resource that actually exists in the snapshot, and that resources appear in valid dependency order. When a reference dangles — for example a child resource whose parent URN is missing — Pulumi refuses to proceed rather than risk corrupting your infrastructure further.

This is a state problem, not a cloud problem. Your real resources are usually fine; the recorded description of them is inconsistent, often after an interrupted operation, a manual state edit, or a bad merge of concurrent updates.

error: snapshot integrity failure; refusing to use it: child resource
urn:pulumi:prod::app::aws:ec2/subnet:Subnet::a refers to missing parent
urn:pulumi:prod::app::aws:ec2/vpc:Vpc::main

Symptoms

• Every pulumi preview, pulumi up, pulumi refresh, or pulumi destroy on the stack fails immediately with snapshot integrity failure.
• The message names a specific broken reference: refers to missing parent, refers to missing provider, or a dependency/deletedWith that does not resolve.
• The failure started right after a crashed/cancelled update, a pulumi state delete, or a hand-edited pulumi stack export | pulumi stack import round-trip.
• Two people ran pulumi up against the same stack at nearly the same time.

Common Root Causes

1. An interrupted or killed operation

If the process was killed (Ctrl-C twice, CI timeout, OOM) between writing two related resources, the snapshot can be left with a child but no parent, or a resource that references a provider that was rolled back.

2. A manual state edit that removed a referenced resource

Deleting a parent with pulumi state delete <urn> while children still point at it leaves those children dangling.

child resource ... refers to missing parent ...

3. A hand-edited stack export re-imported with mistakes

Editing the JSON from pulumi stack export and re-importing it is powerful but easy to get wrong — a removed entry, a mistyped URN, or resources listed out of dependency order all trip the integrity check.

4. Concurrent updates to the same stack

Two updates writing the same backend state can interleave and produce an inconsistent snapshot. Pulumi’s locking prevents most of this, but self-managed backends or forced --yes runs can still collide.

5. A backend/storage sync issue

With object-storage backends (S3, GCS, Azure Blob), an eventually-consistent or partial write can surface as a truncated or stale snapshot.

How to Diagnose

Export the raw snapshot so you can inspect it (this works even when normal commands refuse to run):

pulumi stack export --file snapshot.json

Find the dangling reference the error names — list every URN, then check which parents are referenced but absent:

# All resource URNs in the snapshot
jq -r '.deployment.resources[].urn' snapshot.json | sort > urns.txt

# Every parent referenced
jq -r '.deployment.resources[].parent // empty' snapshot.json | sort -u > parents.txt

# Parents that are referenced but do not exist as resources
comm -13 urns.txt parents.txt

Check for pending operations, which often accompany a corrupted snapshot:

jq '.deployment.pending_operations' snapshot.json

Fixes

Let Pulumi repair it automatically. Modern CLIs can rewrite the snapshot to fix common integrity problems:

pulumi state repair

This loads the snapshot, applies fixes (removing dangling references and reordering), and writes back a valid state. Re-run pulumi preview afterward to confirm.

Restore from history. The managed Pulumi Cloud backend keeps prior state versions — roll back to the last good one:

pulumi stack history
pulumi stack import --file <known-good-export.json>

For self-managed backends, restore the previous .pulumi/stacks/<stack>.json (or its .bak) from your object store’s versioning.

Fix the export by hand, then re-import. When repair cannot resolve it, edit the exported JSON: remove the orphaned child resource (or restore the missing parent entry), keeping resources in dependency order, then re-import:

# edit snapshot.json to remove the dangling child or add the missing parent
pulumi stack import --file snapshot.json
pulumi preview

Remove the specific broken resource from state. If a single child is the culprit and the real cloud object is gone (or you will re-import it), delete just that entry:

pulumi state delete 'urn:pulumi:prod::app::aws:ec2/subnet:Subnet::a'

Then reconcile with reality using pulumi refresh and, if needed, pulumi import.

Reconcile with the cloud. After any state surgery, run a refresh so the snapshot matches what actually exists:

pulumi refresh
pulumi preview

What to Watch Out For

• Always pulumi stack export --file backup.json before editing state — you want a rollback point.
• Keep resources in dependency order in a hand-edited export; parents must appear before the children that reference them.
• Never edit state while another update might run; disable timers/CI or acquire the lock first.
• Enable versioning on self-managed state buckets so you can restore a prior snapshot.
• A clean pulumi preview (no unexpected replacements or deletes) is the signal the snapshot is healthy again.

Related Guides

• Pulumi Error: ‘pending operations’ — Troubleshooting Guide
• Pulumi Error: ‘resource cannot be deleted because it is protected’ — Troubleshooting Guide
• Pulumi Error: ‘resource already exists’ — Troubleshooting Guide