GitHub Actions matrix value not available in the container image name
A container image name referenced a matrix value, but the matrix vector was misnamed or undeclared, so the expression resolved to empty. Docker then tries to pull an image with a missing tag and fails.
What this error means
Container jobs in a matrix fail to pull because the image tag is blank or malformed where a matrix value should be.
github-actions
##[error]Docker pull failed: invalid reference format
image: node:
expected node:${{ matrix.node }} -> node: (empty)Common causes
Matrix key name mismatch
The image uses matrix.node-version but the matrix declares "node", so the referenced key is undefined and renders empty.
Value not declared in the matrix vector
The expected key exists nowhere in the matrix, so every combination produces an empty interpolation.
How to fix it
Match the matrix key to the expression
- Make the matrix key name identical to what the image expression references.
- Confirm each combination produces a valid tag.
- Re-run.
.github/workflows/ci.yml
strategy:
matrix:
node: ['18', '20', '22']
runs-on: ubuntu-latest
container: node:${{ matrix.node }}-bookwormHow to prevent it
- Keep matrix key names and expression references identical.
- Echo the resolved image tag in a debug step when a matrix drives the image name.
Related guides
GitHub Actions matrix value not interpolating in job nameFix a GitHub Actions job name showing the literal expression instead of the matrix value - the name field nee…
GitHub Actions "Docker pull failed" for a job container imageFix the GitHub Actions error where the job container image cannot be pulled - bad tag, private registry, or a…
GitHub Actions matrix include adds an undeclared keyFix the GitHub Actions confusion where a matrix include entry adds a new combination instead of extending exi…