Stacktape provides two rollback commands for recovering from bad deployments. stacktape rollback re-deploys a previous good version using stored deployment artifacts. stacktape stack recover triggers Stacktape's CloudFormation rollback flow when a deployment leaves the stack in a failed state. Neither command requires your local source code or config file — version rollback works from stored deployment artifacts and CloudFormation state rather than rebuilding from your current working tree.
When to use each rollback type
Stacktape's two rollback commands serve different failure scenarios. Choosing the wrong one wastes time or leaves the stack in a worse state.
| Scenario | Command | What it does |
|---|---|---|
| Last deploy succeeded but introduced a bug | stacktape rollback | Re-deploys a previous version's CloudFormation template as a new deployment |
| Deploy failed and you want to continue from the failure | stacktape deploy | Fixes and continues a stack left in CREATE_FAILED or UPDATE_FAILED, keeping what the failed deploy created |
| Update failed and you want to undo it instead | stacktape stack recover | Triggers Stacktape's CloudFormation rollback flow and cleans up rolled-back deployment artifacts |
| First deploy failed and you want to remove it | stacktape delete | Deletes the stack and everything the failed deploy created |
| You want to undo multiple deploys back | stacktape rollback --rollback-steps 3 | Targets an older version by stepping back N versions |
Version rollback
The stacktape rollback command re-deploys a previously working CloudFormation template and reuses the original deployment artifacts from that version. It creates a new deployment version — it does not rewrite history. This is the command you want when your stack is healthy (last deploy succeeded) but the application is broken due to a code or config change you need to undo.
How it works
Every successful Stacktape deployment stores a versioned snapshot of the CloudFormation template and all packaged artifacts in the deployment bucket. Versions follow the format v000001, v000002, etc.
When you run stacktape rollback, Stacktape:
- Resolves the target version — determines which version to roll back to, either by an explicit
--target-versionflag or by stepping back N versions (default: 1). - Verifies artifacts for the target version — confirms the CloudFormation template and all referenced deployment artifacts still exist.
- Checks rollback safety — inspects the current stack's rollback safety metadata and warns if the config uses features that may not replay cleanly (e.g.,
$Filedirective,after:deployhooks, TypeScript transforms, custom directives). - Deploys the old template — downloads the old CloudFormation template, patches the version output, uploads it, and triggers a CloudFormation stack update.
- Restores bucket-synced content — Stacktape attempts to restore bucket-synced content from the target version's manifest. If that restore fails, Stacktape warns that static websites may need redeployment from the original commit.
The rolled-back template is deployed as a new version number. Rolling back from v000005 to v000003 creates v000006 containing the v000003 template. After a successful rollback, the stack has a new deployment version, so the next normal deploy continues from that version.
Basic usage
Roll back one version (the most common case — undoes the most recent deploy):
Roll back to a specific version:
Roll back multiple steps:
Listing available versions
Before rolling back, check which versions are available:
This prints the current version and versions found in Stacktape's previous-version list. Stacktape still verifies the selected version's artifacts before performing the rollback. Versions are numbered sequentially, so you can correlate them with your deployment history. Old versions may be cleaned up based on previousVersionsToKeep; if a target version is no longer available, Stacktape cannot roll back to it.
Artifact retention
Stacktape keeps deployment artifacts for previous versions so they remain available as rollback targets. Once a version's artifacts are cleaned up, you can no longer roll back to it. Retention is controlled via deploymentConfig.previousVersionsToKeep — higher values keep more rollback targets but retain more deployment artifacts, which can increase storage costs.
Higher retention gives you more rollback targets but keeps more deployment artifacts in storage. Increase retention if your team needs longer rollback windows; decrease it if you deploy very frequently and want to minimize storage costs.
Rollback safety warnings
Not all deployments can be rolled back cleanly. After Stacktape verifies the target version artifacts, rollback safety checks print warnings without blocking the rollback. The safety checks cover:
- State-embedding directives (
$Fileand similar) — the rolled-back template contains values that were baked in at the original deploy time. If the referenced file has changed since then, the rollback uses the old content. - TypeScript transforms — Stacktape warns when the deployment used TypeScript transforms, because those transforms are not captured in the CloudFormation template and may require manual review after rollback.
after:deployhooks — Stacktape warns when the config hasafter:deployhooks (database migrations, cache warming, etc.); those hooks are not re-executed during rollback.- Custom directives — results from custom directives were captured at original deploy time.
When rollback safety metadata is present, Stacktape prints warnings only for the safety fields that are set. The command does not block the rollback. Older deployments without rollback safety metadata still produce a cautionary warning. In all cases, the rollback is still a CloudFormation stack update and can fail for normal CloudFormation reasons. For configs that use these features, review the warnings and decide whether manual follow-up is needed after the rollback completes.
When rollback safety metadata is not found — typically because the deployment predates rollback support — Stacktape proceeds with the rollback but warns that results may be unpredictable if the config used any of the features above.
CloudFormation rollback
The stacktape stack recover command triggers Stacktape's CloudFormation rollback flow for the target stack and then cleans up any deployment artifacts that were uploaded during the failed deployment. Use this when a deployment failed and left your stack in a broken state — it does not target a specific previous version like stacktape rollback does.
When to use stack recover
A failed deployment keeps what it created and leaves the stack in CREATE_FAILED or UPDATE_FAILED unless automatic rollback is on. Deploying again continues from the failure. Use stacktape stack recover when you want to undo a failed update instead. For a failed first deployment there is no earlier state to return to: CloudFormation deletes its resources and leaves an empty ROLLBACK_COMPLETE stack, which you then delete, so run stacktape delete directly. The command triggers Stacktape's CloudFormation rollback flow and then deletes the artifacts uploaded during the failed deployment. Note that CloudFormation rollback itself can still fail in some cases — if the stack cannot be restored, manual recovery through the AWS Console or AWS CLI may be required.
You do NOT need this command when:
- The stack is healthy and you want to go back to an earlier version — use
stacktape rollbackinstead - The deploy failed but the stack already rolled back on its own — the stack is already recovered
Basic usage
After a successful stack recover, Stacktape automatically cleans up any deployment artifacts that were uploaded during the failed deployment.
Rollbacks FAQ
What's the difference between stacktape rollback and stacktape stack recover?
stacktape rollback is a version-targeted operation — it picks a specific previous deployment version, verifies its artifacts still exist, and re-deploys its CloudFormation template as a new version. Use it when your stack is healthy but the latest code or config is wrong. stacktape stack recover is a recovery operation — it triggers Stacktape's CloudFormation rollback flow to unstick a stack left in a failed state, then cleans up artifacts from the failed deployment. Use it when the stack itself is broken, not just the application.
What happens to my database during a rollback?
stacktape rollback does not run reverse database migrations; it deploys the old CloudFormation template. If your schema changed between versions (for example, you added a column via a deployment script), you need to review and handle any schema or data changes separately before and after the rollback.
How do I know which version to roll back to?
Run stacktape rollback --list-versions to see all available versions with their version numbers. Versions are numbered sequentially (v000001, v000002, etc.), so you can correlate them with your deployment history. For most incidents, rolling back one step (the default) is correct — you're undoing the most recent change.
Can I roll forward after a rollback?
Yes. A version rollback creates a new deployment version (e.g., rolling back from v000005 to v000003 creates v000006). After a successful version rollback, Stacktape reports the new deployment version. You can then deploy normally with stacktape deploy or run another rollback to any retained version.
Why can't I roll back to an old version?
Each version stays a valid rollback target only while its deployment artifacts are retained. Once a version's artifacts are cleaned up, stacktape rollback can no longer restore it — even though it may still appear in your deployment history. Retention is controlled by deploymentConfig.previousVersionsToKeep; raise it if you need a longer rollback window, at the cost of keeping more artifacts in storage.
Does CloudFormation rollback always succeed?
Not always. AWS CloudFormation rollback can fail if a resource can't be restored to its previous state — for example, if someone manually deleted a resource outside of CloudFormation, or if a resource's previous configuration is no longer valid (a deleted AMI, a deregistered domain). When this happens, the stack ends up in a state that requires manual recovery through the AWS Console or AWS CLI before further Stacktape deployments can proceed.