CloudConsole

aws cloudformation describe-stacks

Updated 16 November 2026 · How we write and check guides

Short answer

aws cloudformation describe-stacks --stack-name my-stack returns a stack's status, status reason, parameters, outputs, tags and capabilities. Without --stack-name it lists every stack in the Region that has not been deleted; pair it with --query to pull out outputs such as an API URL.

Terminal running aws cloudformation describe-stacks --stack-name… with its example output
A worked example from this page with its output. Copy commands from the text below, not from the image.

What the command does

It returns an array under Stacks. The fields people read most are StackStatus (for example CREATE_COMPLETE, UPDATE_ROLLBACK_COMPLETE, ROLLBACK_COMPLETE), StackStatusReason, Outputs, Parameters, LastUpdatedTime and EnableTerminationProtection.

It tells you that something failed, but rarely why. The reason is almost always on a resource event, which is what describe-stack-events shows.

Syntax

aws cloudformation describe-stacks [--stack-name <name-or-stack-id>]

Worked examples

Status of one stack:

aws cloudformation describe-stacks --stack-name orders-api \
  --query "Stacks[0].[StackStatus,StackStatusReason,LastUpdatedTime]" --output text

Read an output value into a variable, the most common scripting use:

api_url=$(aws cloudformation describe-stacks --stack-name orders-api \
  --query "Stacks[0].Outputs[?OutputKey=='ApiUrl'].OutputValue" --output text)

All outputs as a table:

aws cloudformation describe-stacks --stack-name orders-api \
  --query "Stacks[0].Outputs[].[OutputKey,OutputValue]" --output table

Every stack that is not in a healthy final state:

aws cloudformation describe-stacks \
  --query "Stacks[?!contains(['CREATE_COMPLETE','UPDATE_COMPLETE','IMPORT_COMPLETE'], StackStatus)].[StackName,StackStatus]" \
  --output table

Parameters the stack was deployed with:

aws cloudformation describe-stacks --stack-name orders-api \
  --query "Stacks[0].Parameters[].[ParameterKey,ParameterValue]" --output text

Block a script until an update finishes (fails if it rolls back):

aws cloudformation wait stack-update-complete --stack-name orders-api

Before you redeploy

Check three things with this command before re-running a failed pipeline. Is the stack in a state that accepts updates at all (anything ending _COMPLETE except ROLLBACK_COMPLETE)? Is termination protection on, if you are about to delete and recreate it? And are the parameters what you expect, since a pipeline may have passed an empty or stale value that caused the failure in the first place?

aws cloudformation describe-stacks --stack-name orders-api \
  --query "Stacks[0].{status:StackStatus,protected:EnableTerminationProtection,drift:DriftInformation.StackDriftStatus}"

Status values that need action

StatusWhat it meansNext step
ROLLBACK_COMPLETECreation failed and was rolled backDelete the stack and create it again; see this error
UPDATE_ROLLBACK_FAILEDAn update failed and the rollback also failedcontinue-update-rollback
DELETE_FAILEDSome resources could not be deletedFix the blocker, or retry delete with retained resources
UPDATE_ROLLBACK_COMPLETEUpdate failed, stack is back to the old stateRead events, fix, deploy again
*_IN_PROGRESSOperation still runningWait, or follow events

Gotchas

  • Deleted stacks need the stack ID. Listing without a name skips deleted stacks; describing a deleted stack by name fails with "does not exist". Use the full stack ID ARN, or aws cloudformation list-stacks --stack-status-filter DELETE_COMPLETE.
  • Regional. "Stack does not exist" is very often the wrong --region.
  • Outputs from nested stacks belong to the nested stack. Describe it by its own name or ID (shown as a resource in the parent).
  • Secrets in parameters. Parameters with NoEcho are masked as asterisks; others, including passwords passed in plain text, are shown to anyone with describe access.

Questions

How do I get a CloudFormation output value in a shell script?

Use --query "Stacks[0].Outputs[?OutputKey=='Name'].OutputValue" --output text and capture it with $(...). Exported values can also be read with aws cloudformation list-exports.

How do I list all CloudFormation stacks?

Run describe-stacks with no --stack-name for full details, or aws cloudformation list-stacks for a lighter summary that can also include deleted stacks.

How do I find why my stack failed?

describe-stacks shows only a summary. Run aws cloudformation describe-stack-events --stack-name <name> and look for the first event with a FAILED status.

When this happens away from your desk

A failed deploy at the end of the day leaves a stack in a state someone has to check. CloudConsole, a phone app for AWS, is built to show resources and their alarms on a phone.

About the app → · Download on the App Store

Sources