GitHub Actions matrix artifact name collision (upload-artifact v4) in CI

By Daniel Zoghalchali·Latchkey

actions/upload-artifact v4 makes each artifact immutable and rejects a second upload with the same name. In a matrix, every leg uploading to one fixed name collides. Each combination must produce a distinct artifact name.

What this error means

The second and later matrix legs fail their upload step with "Failed to CreateArtifact: ... an artifact with this name already exists on the workflow run".

Error: Failed to CreateArtifact: Received non-retryable error: Failed request:
(409) Conflict: an artifact with this name already exists on the workflow run

Common causes

All matrix legs upload the same artifact name

A hardcoded name like build-output is reused by every leg. Under v4 immutability, the first upload wins and the rest conflict.

v4 no longer merges same-named uploads

Unlike v3, v4 does not append to an existing artifact, so duplicate names across the run are a hard error.

How to fix it

Include matrix values in the artifact name

1. Add each distinguishing matrix value to the artifact name.
2. Confirm every leg produces a unique name.
3. Optionally merge them afterward with a download/merge step.

- uses: actions/upload-artifact@v4
  with:
    name: build-${{ matrix.os }}-node${{ matrix.node }}
    path: dist/

Merge per-leg artifacts downstream

Use the artifact merge action or a pattern download in a later job to combine the uniquely named per-leg artifacts.

- uses: actions/download-artifact@v4
  with:
    pattern: build-*
    merge-multiple: true

How to prevent it

• Suffix artifact names with matrix values so each leg is unique.
• Remember v4 artifacts are immutable and do not merge by name.
• Combine per-leg artifacts in a follow-up job when you need one bundle.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions