Pulumi Upgrade Failure: No Automatic Rollback for Provider Plugins

Question

When executing pulumi upgrade, the CLI downloads and installs provider plugins into the local .pulumi/cache directory. If the process aborts mid-download or a plugin fails to initialize, the stack may remain in a failed state while the new plugin files persist in the cache.
The current recovery workflow requires manual intervention: uninstalling the failed plugin version, reinstalling the previous stable version, and running pulumi refresh. There is currently no native CLI flag, such as --rollback, to automate the reversion of provider changes upon an error.
This lack of automated recovery creates a risk of state inconsistency where subsequent upgrade attempts fail due to stale or mismatched plugin files in the local environment.

Is there a specific command or configuration to atomically revert provider plugin changes if an upgrade fails halfway?
What is the safest method to clear the .pulumi/cache to prevent stale plugin files from interfering with manual recovery efforts?
Is there a documented roadmap for a built-in rollback mechanism to handle provider-level upgrade failures?

Tasadduq Burney · Answer

Direct Answers No atomic rollback flag exists. The Pulumi CLI does not provide a --rollback option or any native mechanism to automatically revert provider plugin changes when pulumi upgrade fails mid-download or during initialization. The upgrade process is linear; a failure leaves the stack in a failed state until you intervene manually. Safest cache clearing: Run pulumi plugin purge to remove all cached plugins, or delete the .pulumi/cache directory directly. Both approaches force fresh downloads on the next operation. pulumi plugin purge is preferable because it is a supported CLI command and avoids accidental deletion of unrelated files. No documented roadmap entry. As of the current Pulumi CLI 3.x releases, there is no public roadmap item confirming a built-in rollback feature for provider-level upgrade failures. Feature requests exist in the issue tracker, but no release timeline has been announced. Manual Recovery Procedure Identify the failed plugin version. Run pulumi plugin list and note the provider name and version that was being installed when the upgrade aborted. Remove the partial/failed plugin. Execute pulumi plugin rm (or pulumi plugin uninstall in older CLI versions). Reinstall a known stable version. Run pulumi plugin install matching the version your stack configuration expects. Clear the cache. Run pulumi plugin purge to eliminate any stale files that could interfere with subsequent runs. Reconcile stack state. Execute pulumi refresh to synchronize the stack's state file with the actual infrastructure. Do not run pulumi up until refresh completes without errors. Critical Assumptions and Verification Commands above assume Pulumi CLI 3.x or later. Earlier versions may use slightly different syntax for plugin management. Always back up your stack state (pulumi stack export) before removing plugins. A corrupted state file combined with plugin changes can make recovery harder. Confirm the reinstalled plugin version matches the provider version pinned in your Pulumi.yaml or project configuration. Version mismatches are a common cause of repeated failures. After pulumi refresh, inspect the output for any resources showing failed or deleted status. These indicate state drift that must be resolved before further deployments. One Diagnostic Detail That Changes the Recommendation If the failure occurred during a provider schema upgrade (e.g., a major version bump that changes resource schemas) rather than a simple plugin download, the stack's state file may already contain references to the new schema. In that case, pulumi refresh alone may not suffice and you may need to edit the state file or use pulumi state delete for affected resources. Please confirm whether the upgrade was a patch/minor version (plugin binary only) or a major version with schema changes.

Pulumi Upgrade Failure: No Automatic Rollback for Provider Plugins

1 answer

Direct Answers

Manual Recovery Procedure

Critical Assumptions and Verification

One Diagnostic Detail That Changes the Recommendation

Your perspective belongs here.

0 question comments