SAM Doctor

ERROR REFERENCE

InvalidSamDocumentException (template schema validation)

SAM or CloudFormation rejected the template before creating any resource: the document failed schema validation, or a resource type does not recognize one of its properties. The template never reached AWS as a change — the shape of the file itself is the failure.

WHAT IT MEANS

What this error means

The same family shows up in several phrasings:

The most common causes are ordinary editing accidents: a property indented into the wrong block, a copy-paste from a different resource type, or a template that declares SAM resource types (AWS::Serverless::*) after losing its Transform: AWS::Serverless-2016-10-31 line.

FIX

How to fix it

  1. Validate locally before deploying: 
    sam validate --lint
    The lint pass runs cfn-lint rules and reports the resource id and property path, which is faster than a deploy round-trip.
  2. Read the resource id and property in the error. Compare that property against the reference page for the exact resource type — an unsupported property is often a valid property of a different type (a function property on a state machine, an API property on a function).
  3. Check the nesting level. YAML indentation moves properties between blocks silently; a property one level too deep or too shallow becomes "not defined for resource of type".
  4. Confirm the Transform line survives. Templates using AWS::Serverless::* types need Transform: AWS::Serverless-2016-10-31 at the top level.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the schema-validation phrasings (high confidence) and keeps them distinct from single-property mismatches, which have their own rule. Runs locally; no AWS access, no log upload. 

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

RELATED