GitHub Actions matrix value not available in the container image name

By Daniel Zoghalchali·Latchkey

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.

##[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

1. Make the matrix key name identical to what the image expression references.
2. Confirm each combination produces a valid tag.
3. Re-run.

strategy:
  matrix:
    node: ['18', '20', '22']
runs-on: ubuntu-latest
container: node:${{ matrix.node }}-bookworm

How 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.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions