CircleCI Cannot Use Environment Variable in Image Name

By Kaveh Alemi·Latchkey

The docker.image field is resolved at config-processing time, before any job shell runs, so shell environment variables do not interpolate there. Only pipeline parameters and certain pipeline values expand in image names.

What this error means

The job tries to pull an image with the literal variable in the name, or fails because the image tag did not expand.

Error: image "cimg/node:$NODE_VERSION" not found.
Environment variables are not interpolated in the docker image field.

Common causes

Shell env var used in image field

NODE_VERSION from a context or env is not available when the image is resolved.

Expecting runtime interpolation

Image resolution happens before the job shell exists, so runtime values cannot be used.

How to fix it

Use a pipeline parameter

Parameterize the image tag with a declared parameter, which is resolved at config time.

parameters:
  node_version:
    type: string
    default: '20.11'

jobs:
  build:
    docker:
      - image: cimg/node:<< pipeline.parameters.node_version >>
    steps:
      - run: node --version

How to prevent it

• Use pipeline parameters, not shell env vars, in image names.
• Resolve image tags at config-processing time.
• Pin image versions explicitly where possible.

Frequently asked questions

Related guides

References

• GitHub Actions documentation