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.

pulumi output

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

Diagnose it: state, credentials, or drift?

Infrastructure failures in CI are usually about state access or credentials rather than the configuration itself. Confirm the runner can reach and lock state before reading the plan output.

Terminal

terraform init -backend=true -input=false
terraform providers
terraform plan -input=false -no-color -detailed-exitcode
#   exit 0 = no changes, 2 = changes present, 1 = error

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.

.github/workflows/deploy.yml

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

Recover from a known-good snapshot

Export the current state with pulumi stack export --file stack.json if it is partially readable.
If it is corrupt, restore the previous version from your backend’s object versioning (S3/GCS) and pulumi stack import it.
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

What causes Pulumi "failed to load checkpoint"?

There are 2 common causes: truncated or partially written state and pulumi version skew. 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).

How do I fix Pulumi "failed to load checkpoint"?

There are 2 fixes depending on which cause you have: pin and align the pulumi version and recover from a known-good snapshot. Work through them in order, since the first is the most common.

What does Pulumi "failed to load checkpoint" actually mean?

A Pulumi command fails at load time with failed to load checkpoint, often with a JSON parse error or an integrity-check failure.

How do I stop Pulumi "failed to load checkpoint" happening again?

Enable object versioning on the state bucket so you can roll back a bad checkpoint. The prevention section lists 3 changes that keep it from recurring.