🚨 AWS Error: 'Requires capabilities : [CAPABILITY_IAM]' — Cause, Fix, and Troubleshooting Guide

Overview

CloudFormation refuses to create or update a stack that provisions IAM resources, custom-named resources, or macro/transform expansions unless you explicitly acknowledge it by passing a capability flag. This is a safety gate: because these templates can grant privileges or run arbitrary transforms, AWS makes you opt in per operation rather than silently applying them.

You will see it surface from the CLI or a pipeline:

An error occurred (InsufficientCapabilitiesException) when calling the CreateStack operation: Requires capabilities : [CAPABILITY_IAM]

The named-IAM and macro variants read similarly:

Requires capabilities : [CAPABILITY_NAMED_IAM]
Requires capabilities : [CAPABILITY_AUTO_EXPAND]

It occurs whenever the template contains IAM resources (CAPABILITY_IAM), IAM resources with explicit names (CAPABILITY_NAMED_IAM), or a Transform / macro / nested AWS::Include that must be expanded (CAPABILITY_AUTO_EXPAND).

Symptoms

• create-stack / update-stack / deploy fails immediately with InsufficientCapabilitiesException.
• The error names exactly which capability is required.
• A template that deployed fine before now fails after someone added an IAM role, policy, or a Transform.

aws cloudformation create-stack --stack-name app --template-body file://template.yaml

An error occurred (InsufficientCapabilitiesException) when calling the CreateStack operation: Requires capabilities : [CAPABILITY_NAMED_IAM]

Common Root Causes

1. The template creates IAM resources

Any AWS::IAM::Role, Policy, User, Group, InstanceProfile, or ManagedPolicy requires at least CAPABILITY_IAM.

2. The IAM resources have explicit names

If any IAM resource sets a RoleName, PolicyName, UserName, etc., AWS escalates the requirement to CAPABILITY_NAMED_IAM (custom names can’t be auto-deconflicted).

3. The template uses a macro or transform

Transform: AWS::Serverless-2016-10-31 (SAM), AWS::Include, AWS::LanguageExtensions, or a custom macro requires CAPABILITY_AUTO_EXPAND.

4. Nested stacks that themselves need capabilities

A parent stack expanding children that create IAM/macros needs the corresponding capabilities passed at the parent.

How to diagnose

Step 1: Check what the template actually declares

grep -nE 'AWS::IAM::|RoleName|PolicyName|UserName|Transform:' template.yaml

14:  AppRole:
15:    Type: AWS::IAM::Role
17:      RoleName: my-app-exec-role
2:Transform: AWS::Serverless-2016-10-31

An explicit RoleName → CAPABILITY_NAMED_IAM; a Transform → CAPABILITY_AUTO_EXPAND.

Step 2: Let a change set tell you the requirement

aws cloudformation create-change-set --stack-name app --change-set-name c1 \
  --template-body file://template.yaml --change-set-type CREATE 2>&1 | grep -i capabilit

Fixes

Pass the capability the error asks for

aws cloudformation deploy --stack-name app --template-file template.yaml \
  --capabilities CAPABILITY_NAMED_IAM

For plain (auto-named) IAM resources:

aws cloudformation create-stack --stack-name app --template-body file://template.yaml \
  --capabilities CAPABILITY_IAM

Combine capabilities when a template needs several

aws cloudformation deploy --stack-name app --template-file template.yaml \
  --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND

Set it in IaC, not just the CLI

In samconfig.toml, the CDK, or a pipeline action, declare capabilities = "CAPABILITY_NAMED_IAM" so every deploy carries it and CI doesn’t break on the first IAM change.

What to watch out for

• CAPABILITY_NAMED_IAM is a superset requirement of CAPABILITY_IAM for named resources — passing only CAPABILITY_IAM still fails if any IAM resource is explicitly named.
• Prefer letting CloudFormation auto-generate IAM names (omit RoleName) so you only need CAPABILITY_IAM and avoid name-collision failures on recreate.
• Passing a capability is an acknowledgement, not a grant: the deploying principal still needs the underlying iam:* permissions to actually create the resources.
• CAPABILITY_AUTO_EXPAND runs macros with their own permissions — review what a third-party macro does before enabling it.

Related

• AWS Error: ‘ROLLBACK_COMPLETE’ state and can not be updated — a missing capability is a frequent cause of the failed first create.
• AWS Error: ‘MalformedPolicyDocument’ — the IAM policy that CloudFormation is trying to create is itself invalid.
• AWS Error: ‘No updates are to be performed’ — another common CloudFormation update-time failure.