Pulumi "failed to load checkpoint" - Fix Corrupt State in CI

By Kaveh Alemi·Latchkey

Pulumi could not read or deserialize the stack checkpoint - the JSON snapshot of resource state in your backend. It is truncated, corrupt, or in a format a different Pulumi version wrote.

What this error means

A Pulumi command fails at load time with failed to load checkpoint, often with a JSON parse error or an integrity-check failure. The state never loads, so no preview or update can run.

error: failed to load checkpoint: unmarshalling checkpoint: unexpected end of
JSON input
    snapshot integrity failure; refusing to use it

Common causes

Truncated or partially written state

A previous run was killed while writing the checkpoint, leaving a half-written file in the backend (S3/Azure/GCS or a self-managed store).

Pulumi version skew

A newer Pulumi CLI wrote a checkpoint format an older CLI in CI cannot read, or vice versa, so deserialization fails.

How to fix it

Pin and align the Pulumi version

Use the same Pulumi version locally and in CI so the checkpoint format always matches.

- uses: pulumi/actions@v6
  with:
    pulumi-version: 3.130.0

Recover from a known-good snapshot

1. Export the current state with pulumi stack export --file stack.json if it is partially readable.
2. If it is corrupt, restore the previous version from your backend’s object versioning (S3/GCS) and pulumi stack import it.
3. Re-run pulumi preview to confirm the recovered state matches reality before applying.

How to prevent it

• Enable object versioning on the state bucket so you can roll back a bad checkpoint.
• Pin a single Pulumi version across all environments.
• Give Pulumi steps enough time so state writes are not interrupted by a runner timeout.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation