SAM Doctor

ERROR REFERENCE

Embedded stack was not successfully created/updated

With nested stacks (and SAM's AWS::Serverless::Application), the parent stack's event only says an embedded stack failed - that is a symptom, not the cause. The real root cause lives in the child stack's own event stream, and it is often deleted by rollback before anyone reads it.

WHAT IT MEANS

What this event means

CloudFormation reports the nested stack's failure on the parent as a single summary line - Embedded stack ... was not successfully created - with no detail about which resource inside the child stack actually failed or why. That detail exists only in the child stack's own events, and CloudFormation's rollback can delete the child stack, and its event history with it, before it is ever read.

FIX

How to fix it

  1. Capture the child stack's events before rollback deletes them, or redeploy with --disable-rollback to keep the stack around while debugging.
  2. Query the child stack directly (read-only) using the full nested stack ARN from the parent's message - this still works once deletion has started: 
    aws cloudformation describe-stack-events --stack-name <child-stack-arn>
  3. Find the child's first CREATE_FAILED or UPDATE_FAILED resource event and fix that cause; only edit the parent template afterward.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the nested-stack propagation message (high confidence) and reports it instead of the generic CREATE_FAILED or rollback findings, since the parent's own event is not the actionable one. Runs locally; no AWS access, no log upload. 

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

RELATED