aws cloudformation deploy: Usage & Common CI Errors

Deploy or update a CloudFormation stack from a template in one command.

aws cloudformation deploy creates or updates a stack from a template, computing and executing a change set automatically. It is the high-level deploy command (also used under SAM) for infrastructure-as-code on AWS.

What it does

The command uploads/registers your template, builds a change set, and executes it, creating the stack if it does not exist or updating it if it does. You pass parameters with --parameter-overrides and acknowledge IAM/named-resource creation with --capabilities. It waits for completion and returns nonzero on failure.

Common usage

# Deploy a stack with parameters and IAM capability
aws cloudformation deploy \
  --template-file template.yaml \
  --stack-name my-stack \
  --parameter-overrides Env=prod InstanceType=t3.small \
  --capabilities CAPABILITY_NAMED_IAM

# No-op deploys exit 0 instead of failing
aws cloudformation deploy --template-file template.yaml \
  --stack-name my-stack --no-fail-on-empty-changeset

Common error in CI: "No changes to deploy" exit 255 / InsufficientCapabilities

Two classic CI failures: deploy exits 255 with "No changes to deploy. Stack ... is up to date" when nothing changed (it treats an empty change set as an error by default), and "Requires capabilities : [CAPABILITY_IAM]" when the template creates IAM resources. Fix: add --no-fail-on-empty-changeset so idempotent re-runs pass, and pass --capabilities CAPABILITY_IAM (or CAPABILITY_NAMED_IAM for custom-named roles). For a failed update stuck in ROLLBACK_COMPLETE on first create, delete the stack and redeploy.

Key options

Related guides