Serverless Framework "Cannot resolve variable" in CI

By Daniel Zoghalchali·Latchkey

Serverless resolves ${...} variables (env, opt, ssm, self, file references) while loading serverless.yml. One could not be resolved: the source is missing in CI, the path is wrong, or the referenced value is empty.

What this error means

serverless deploy fails with "Cannot resolve variable at \"...\": ..." or "Cannot resolve serverless.yml: Variables resolution errored", naming the unresolved expression.

serverless

Error:
Cannot resolve variable at "provider.environment.API_KEY": Value not found at "env"
source for variable "env:API_KEY"

Common causes

An environment variable is unset in CI

A ${env:VAR} reference resolves to nothing because the secret or variable was not exported to the deploy step.

A missing SSM/file source or wrong path

A ${ssm:...} or ${file(...)} reference points at a parameter or file that does not exist for the deploy identity.

How to fix it

Provide the variable source in CI

Export the env var (from a secret) so the reference resolves at deploy time.

.github/workflows/ci.yml

- run: npx serverless deploy --stage prod
  env:
    API_KEY: ${{ secrets.API_KEY }}

Add a fallback or fix the source path

Give the variable a default, or correct the SSM parameter/file path the deploy reads.

serverless.yml

provider:
  environment:
    API_KEY: ${env:API_KEY, 'default-value'}

How to prevent it

Inject required env vars/secrets into the deploy step.
Use fallbacks for optional variables.
Confirm SSM parameters exist for the deploy identity and region.

Frequently asked questions

What causes ""Cannot resolve variable""?

A ${env:VAR} reference resolves to nothing because the secret or variable was not exported to the deploy step.

How do I fix "Cannot resolve variable"?