Validate templates with cloudformation-validate

The open-source cloudformation-validate project checks JSON and YAML CloudFormation templates locally and is available on GitHub. It can find invalid template structure, broken references, security issues, and best-practice problems. Each finding includes the problem, its severity, and its location in the template.

The tool includes the rules and CloudFormation resource definitions that it needs, so it runs without network access or AWS credentials after installation.

Choose a validation method

• Command line – Run cfn-validate to check one template or every template in a directory from a terminal or an automated build.

• Library – Add the validator to a Rust, Node.js, Python, Go, or JVM application and process the results in your code.

• AWS CDK – Validate templates automatically after CDK synthesizes them.

• Custom rules – Add checks written in CEL, Rego, or the Guard rule language. For supported rule formats and examples, see the Custom Rules Reference on GitHub. For Guard rule syntax, see Validate templates with Guard in this guide.

Install the command-line tool

Open the latest cfn-validate release on GitHub and download the cfn-validate file for your operating system and processor. Follow the installation guide on GitHub to rename the file to cfn-validate, add it to your PATH, and verify the downloaded file.

Run validation

The command uses the following syntax:

cfn-validate TEMPLATE_OR_DIRECTORY [OPTIONS]

Check one template:

cfn-validate template.yaml

Pass a directory to recursively check every .yaml, .yml, and .json file:

cfn-validate ./templates/

The command writes a structured JSON validation report to standard output. Use --format standard for compact output or --format detailed for the default detailed report.

The command returns 0 when it finds no error or fatal diagnostics, 1 when it finds error or fatal diagnostics, and 2 for a usage or initialization error, such as an invalid option or a file that doesn't exist.

For all engines, filters, output formats, and parameters, see the cfn-validate CLI reference on GitHub.

Add custom rules

Use --rule-source to load a custom Rego or CEL rule file. Use --guard-rule-source to load a Guard rule file or directory. You can repeat either option to load multiple rule sources:

cfn-validate template.yaml --rule-source ./rules/my-rule.rego
cfn-validate template.yaml --guard-rule-source ./guard-rules/

For rule formats and examples, see Custom Rules Reference on GitHub.

Embed the validation library

Install the published package for your programming language to run the same offline checks from your application. Create a validation engine once, reuse it for multiple templates, and process the structured diagnostics returned for each template. You can also configure custom CEL, Rego, or Guard rules through the library API.

Language	Published package	API and examples
Rust	cloudformation-validate on crates.io	Rust API and examples
Node.js	@aws/cloudformation-validate on npm	Node.js API and examples
Python	cloudformation-validate on PyPI	Python API and examples
Go	CloudFormation Validate Go module	Go API and examples
JVM (Java or Kotlin)	software.amazon.cloudformation:cloudformation-validate on Maven Central	JVM API and examples

For installation instructions and supported platforms, see the language binding installation guide.

For complete examples in every language and links to each API guide, see Embedding as a library in the project documentation on GitHub.

Use with AWS CDK

If you use AWS CDK, you don't need to install the validator separately. The AWS CDK construct library includes a default CloudFormationValidatePlugin that runs the same checks automatically after synthesizing your CloudFormation templates.

cdk synth

CDK reports possible deployment failures and best-practice findings with its validation results. You can explicitly configure CloudFormationValidatePlugin when you want to add custom Rego or Guard rules.

For plugin configuration, acknowledgments, and validation reporting, see Template and Policy Validation in the AWS CDK API Reference.

Understand validation scope

For the limitations of local validation and steps to take before deployment, see Understand validation scope.