Docs Home Pulumi IaC Pulumi ESC Pulumi Insights Pulumi IDP Pulumi Cloud Packages Tutorials
  1. Docs
  2. Pulumi IaC
  3. Troubleshooting
  4. Editing state files

Editing state files

    The Pulumi IaC engine computes the difference between your program’s code (desired state) and your stack’s state file (current state) to make decisions about what resources to create, read, update, or delete, and in what order. In some cases, you may need to perform edits to your state file, either via the Pulumi CLI (preferred) or by editing the state file in a text editor (as a last resort).

    This page is a guide on how to edit your state file as safely as possible.

    When you might need to edit your state file

    You might need to edit your state file in the following situations:

    • You want to move resources between stacks in the course of refactoring your Pulumi codebase(s)
    • You need to unprotect resources from deletion
    • A Pulumi command fails with an error indicating a corrupt state, for example if you see an I/O error with the text after mutation of snapshot, which can occur in rare scenarios like a network partition during a state file update.

    What to try before editing your state file

    Before manually editing your state file, consider these troubleshooting steps:

    1. Run the pulumi refresh command.
    2. Update to the latest version of the Pulumi CLI (installation instructions) and attempt your operation again.
    3. If a pulumi update failed and a resource was created and shows in your cloud console, but Pulumi is attempting to create the resource again, use the pulumi import command instead of editing your state file.
    4. If you have recently updated the Pulumi CLI, consider downgrading back to the previous known-good version and attempt your operation again.
    5. Update the Pulumi SDK to the version that matches the Pulumi CLI.
    6. If the problem seems to be related to a particular resource type or provider, consider updating your provider dependencies (do this work on a separate git branch so you can easily undo any changes to your Pulumi code).

    These steps don’t always resolve the issue in every case, but they often help and are worth trying before manually editing your state file.

    If your Pulumi issue is causing a serious outage for your workload(s), and Pulumi CLI operations are taking too long, consider the --target option, which allows you to limit the refresh operation only to the resources you specify. (The flag can be specified more than once.)

    The following commands support the --target option:

    • pulumi refresh
    • pulumi preview
    • pulumi up
    • pulumi destroy

    How to edit your state file safely

    If you have determined that it is appropriate and necessary to edit your state file, follow these steps to do so safely:

    Ensure that your team members do not attempt to make updates to your stack while you are editing your state file, e.g., by communicating your intent over a shared chat channel. If someone performs a Pulumi operation that writes to your state file in while you are in the process of editing it, important data loss may occur: either your changes or your teammate’s risk being overwritten.

    1. Save a backup of your state file

    First, you should take a backup of your state file to ensure that any changes you make can be easily reversed. To take a backup of your state file:

    pulumi stack export --file pulumi-state-backup.json

    If you want to undo the changes you make in subsequent steps, you can restore your state file from backup:

    pulumi stack import --file pulumi-state-backup.json

    2. Try targeted fixes with the pulumi state command

    The pulumi state command allows you to make targeted, surgical changes to your state file without the risk of exposing your entire state file in an editor for hand-editing, which can cause additional errors.

    The pulumi state command can help with the following scenarios:

    Refer to the pulumi state reference docs for a complete list of capabilities.

    3. If necessary, export your state file and edit

    If the pulumi state command does not resolve the issue for you, you will need to edit your Pulumi state file in an editor to resolve the issue. First, export the state file again:

    pulumi stack export --file state.json

    The recommendation to export your state file a second time with a different filename from the backup you created earlier is intentional!

    Do not forget to export an additional copy of your Pulumi state file. Failing to do so may make it difficult or impossible to undo your changes once you save your state file to your Pulumi state backend.

    Then, perform any manual edits using the State File reference as a guide. When your edits are complete, import the edited state file with the following command:

    pulumi stack import --file state.json

    State file reference

    Your state file is represented as a JSON object. At the top level, this JSON object has two fields:

    FieldDescription
    versionThe version of the file format. This should not be changed.
    deploymentThe last deployment state of the stack.

    The deployment object has the following fields:

    FieldDescription
    manifestMetadata about the previous deployment. This should not be changed.
    pending_operationsList of the operations that the Pulumi engine started but has not finished.
    resourcesList of resources that Pulumi knows about.

    The resources field is a list, not a set: The order of resources in the list is important and is enforced by the Pulumi engine. Resources in a deployment must be in dependency order - if resource A depends on resource B, resource A must appear after resource B in the list.

    The possible fields of an entry in resources are:

    FieldDescription
    urnThe resource URN, which is a Pulumi-specific universal resource identifier.
    customA boolean indicating whether or not this resource is a custom resource, which means that it uses a resource provider to operate. Component resources are not custom.
    deleteA boolean indicating whether or not this resource is pending deletion.
    idThis resource’s ID, which is a provider-specific resource identifier. This often corresponds to a cloud provider’s identifier for a resource.
    typeThe Pulumi type of this resource.
    inputsA map of inputs for this resource. Inputs are the set of key-value pairs used as an input to a resource provider.
    outputsA map of outputs for this resource. Outputs are the set of key-value pairs that were given to Pulumi by a resource provider after a resource has been provisioned.
    parentA URN for this resource’s parent resource.
    protectA boolean indicating whether or not this resource is protected. Protected resources can not be deleted.
    externalA boolean indicating whether or not this resource is external to Pulumi. If a resource is external, Pulumi does not own its life cycle and it will not ever delete or update the resource. Resources that are read using the get function are external.
    dependenciesA list of URNs indicating the resources that this resource depends on. Pulumi tracks dependencies between resources. It is important that this list be the full list of resources upon which this resource depends.
    initErrorsA list of errors that occurred that prevented the resource from initializing. Some resource providers (most notably Kubernetes) populate this field to indicate that a resource was created but failed to initialize.
    providerReference to the provider responsible for the resource.
      Meet Neo: Your AI Platform Teammate