Requires capabilities : [CAPABILITY_IAM] (InsufficientCapabilitiesException)

WHAT IT MEANS

What this error means

Templates that can change security posture — IAM roles, policies, users — require the caller to opt in with a capability flag. SAM templates hit this constantly because AWS::Serverless::Function generates an execution role behind the scenes. The error names exactly which acknowledgement is missing:

• CAPABILITY_IAM — the template creates or modifies IAM resources with generated names.
• CAPABILITY_NAMED_IAM — the template gives IAM resources explicit names (RoleName, PolicyName, ...). This is a superset concern: named IAM resources need this flag, and CAPABILITY_IAM alone is not enough.
• CAPABILITY_AUTO_EXPAND — the template uses macros or nested applications (AWS::Serverless transform in nested apps, AWS::Include) that expand before deployment.

Note this failure is not IAM denying you anything. If the deploy identity actually lacked IAM permissions, you would see an AccessDenied error instead.

FIX

How to fix it

1. Read which capability the error names and look at the IAM resources in the template first. The flag exists so someone confirms the IAM change is intended — do that confirmation, especially in shared accounts.
2. Pass the smallest required capability for your tool:

   # SAM CLI
   sam deploy --capabilities CAPABILITY_IAM
   
   # samconfig.toml
   capabilities = "CAPABILITY_IAM"
   
   # AWS CLI
   aws cloudformation deploy --capabilities CAPABILITY_IAM
   
   # CDK bootstrap-managed deployments rarely hit this; raw cfn deploys do

   Use CAPABILITY_NAMED_IAM only when the template names IAM resources; both flags can be passed together when needed.
3. For nested serverless applications, add CAPABILITY_AUTO_EXPAND and review the transformed template (aws cloudformation get-template --template-stage Processed) so you know what actually deploys.
4. Re-run the deployment. If it now fails with a different IAM error, that is a real permissions problem, not a capability one.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes InsufficientCapabilitiesException and the Requires capabilities phrasing (high confidence) and distinguishes it from generic change-set failures. Runs locally; no AWS access, no log upload.

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED

Related errors

• Not authorized to perform: sts:AssumeRoleWithWebIdentity — a real identity failure, before CloudFormation is even reached.
• ROLLBACK_COMPLETE state and can not be updated — what a failed first deploy leaves behind.
• The REST API doesn't contain any methods — another change-set-time template failure.

Longer walkthrough: the capability acknowledgement guide.