An SSM parameter referenced by the template could not be resolved

WHAT IT MEANS

What this error means

Parameters: [ssm:/my-app/prod/db-password] cannot be found.

A {{resolve:ssm:...}} or {{resolve:ssm-secure:...}} reference is not read when you write the template or when sam build runs. It is read when CloudFormation builds the change set — in the account and Region being deployed to, as the deploying identity. That is the whole reason this failure surprises people: a parameter you can read from your own terminal proves nothing about the account being deployed to.

Four causes cover almost all of these:

• An environment segment that does not match the target. A path reading /my-app/prod/... deployed to staging is the single most common version, usually because the stage is hardcoded where it should be a parameter.
• A new environment nobody seeded. The template resolves the parameter; it cannot create it. A fresh account has no parameters until something puts them there.
• The wrong Region. Parameter Store is regional. A correct path in another Region reports as simply missing.
• Readable but not decryptable. For ssm-secure, the principal may hold ssm:GetParameters and still lack kms:Decrypt on the key protecting the value.

FIX

How to fix it

1. Look the exact path up the way the deployment did — same credentials, same Region:

   aws ssm get-parameter --name /my-app/prod/db-password --region us-east-1

   Running this with your personal profile instead of the deploy role is the usual way this check gives a falsely reassuring answer.
2. Compare the path against the environment you are deploying to. If the stage is baked into the string, parameterise it so one template cannot point at another environment's values.
3. Seed the parameter in the target account and Region if the environment is new. Resolution is read-only — the deployment will not create it for you.
4. For ssm-secure, test decryption specifically:

   aws ssm get-parameter --name /my-app/prod/db-password --with-decryption

   and confirm the deploy principal has ssm:GetParameters plus kms:Decrypt on the protecting key.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor separates an unresolvable SSM reference (high confidence) from the generic "deployment configuration or parameter resolution failed" finding, and gives the lookup with the Region and decryption flags that actually reproduce it. Runs locally; no AWS access, no log upload.

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

RELATED

Related errors

• Failed to create changeset (configuration or parameter resolution) — the generic finding this replaces for SSM paths.
• Template failed SAM or CloudFormation schema validation — for a malformed reference rather than a missing value.
• AWS denied an API action required by the deployment — when the parameter exists and the principal cannot read it at all.