AWS SAM "Requires capabilities : [CAPABILITY_IAM]" in CI

Your template creates IAM resources (or uses macros/SAM transforms), and CloudFormation requires explicit acknowledgement. The deploy did not pass the needed capability, so CloudFormation refuses the change set.

What this error means

sam deploy fails with "Requires capabilities : [CAPABILITY_IAM]" or "Requires capabilities : [CAPABILITY_AUTO_EXPAND]" (InsufficientCapabilitiesException).

sam

Error: Failed to create changeset for the stack: my-app, ex: Waiter ChangeSetCreateComplete
failed: Requires capabilities : [CAPABILITY_IAM]
An error occurred (InsufficientCapabilitiesException) ...

Common causes

Template creates IAM resources without acknowledgement

Functions, roles, or policies need CAPABILITY_IAM; named roles need CAPABILITY_NAMED_IAM. Without the flag, CloudFormation blocks the change set.

A nested transform or macro needs auto-expand

SAM transforms and macros require CAPABILITY_AUTO_EXPAND, which must be passed alongside the IAM capability.

How to fix it

Pass the required capabilities

Acknowledge IAM creation (and auto-expand for transforms) on the deploy command.

Terminal

sam deploy --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
  --stack-name my-app --resolve-s3 --no-confirm-changeset

Set capabilities in samconfig.toml

Persist the capabilities so every CI deploy includes them.

samconfig.toml

[default.deploy.parameters]
capabilities = "CAPABILITY_IAM CAPABILITY_AUTO_EXPAND"

How to prevent it

Pass CAPABILITY_IAM whenever the template creates IAM resources.
Add CAPABILITY_NAMED_IAM when you name roles explicitly.
Keep capabilities in samconfig.toml so CI is consistent.