Introduction

A common point of confusion is that aws cloudformation validate-template does not take a --capabilities argument the way stack creation and deployment commands do. Validation is not where you acknowledge IAM or macro capabilities. Instead, validate-template reports which capabilities the template requires, and you pass those capabilities later to create-stack, update-stack, or deploy.

What validate-template Actually Does

The command checks whether a CloudFormation template is structurally valid and whether CloudFormation can parse it.

A basic example:

aws cloudformation validate-template \
  --template-body file://template.yaml

This validates the template and returns metadata such as:

• parameter declarations
• template description
• required capabilities

The important detail is that the output can tell you that the template requires CAPABILITY_IAM or CAPABILITY_NAMED_IAM, but you do not supply that acknowledgement to validate-template itself.

Read the Returned Capabilities

If the template contains IAM resources, CloudFormation may report required capabilities in the validation response.

For example, the response may include something conceptually like:

1{
2  "Capabilities": [
3    "CAPABILITY_NAMED_IAM"
4  ]
5}

That is CloudFormation telling you what later stack operations must acknowledge.

This is why the wording matters:

• validation reports capabilities
• stack execution commands require capabilities

Those are separate steps.

Where You Actually Pass --capabilities

When you create or update the stack, then you supply the required capability acknowledgement.

Example with create-stack:

1aws cloudformation create-stack \
2  --stack-name my-stack \
3  --template-body file://template.yaml \
4  --capabilities CAPABILITY_NAMED_IAM

Example with deploy:

1aws cloudformation deploy \
2  --stack-name my-stack \
3  --template-file template.yaml \
4  --capabilities CAPABILITY_NAMED_IAM

This is the step where CloudFormation needs your explicit acknowledgement that the template can create or modify privileged resources.

The same idea applies in CI pipelines. A common safe flow is:

1. run validate-template
2. inspect or log the required capabilities
3. run deploy or create-stack with the matching --capabilities value

That keeps validation and execution responsibilities separate instead of trying to force them into one command.

Common Capability Values

The most commonly encountered values are:

• 'CAPABILITY_IAM'
• 'CAPABILITY_NAMED_IAM'

Use CAPABILITY_NAMED_IAM when the template creates IAM resources with custom names. If you are unsure which one is needed, check the validation output or the stack error message.

Some advanced templates involving transforms or macros may require additional acknowledgement in other contexts, but the core confusion around validate-template is usually about IAM capabilities.

If the deploy command later fails with a capability-related error, that usually means one of two things:

• the template contains privileged resources and you did not pass the required capability
• the validation output already warned you, but the execution step ignored it

That is another reason validation output should be read, not treated as noise.

Why Validation Still Matters

Even though validate-template does not execute the stack, it is still useful because it catches issues early and tells you what capabilities will be required later.

That makes it a good preflight step in CI or local development:

1. validate the template
2. inspect required capabilities
3. run deploy or stack update with the right --capabilities

This is safer than skipping validation and discovering a preventable issue only at deploy time.

Common Pitfalls

• Trying to pass --capabilities directly to validate-template.
• Assuming validation and deployment acknowledge capabilities at the same stage.
• Ignoring the validation response that already reports which capabilities are required.
• Using CAPABILITY_IAM when the template actually needs CAPABILITY_NAMED_IAM.
• Treating capability errors as template syntax errors instead of execution-time acknowledgements.

Summary

• 'validate-template does not take --capabilities as input.'
• It reports the capabilities the template requires.
• Pass those capabilities later to create-stack, update-stack, or deploy.
• For IAM resources, the common values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM.
• Use validation as a preflight check, then apply the required capability flags at stack execution time.