GitHub Actions "an artifact with this name already exists" (upload-artifact v4)
actions/upload-artifact@v4 makes artifacts immutable and unique per run, so two uploads with the same name in one run collide. This usually happens when every matrix leg uploads to the same artifact name.
What this error means
An upload-artifact@v4 step fails with "an artifact with this name already exists", typically on the second matrix leg that tried to reuse a name the first leg already created.
Error: Failed to CreateArtifact: Received non-retryable error:
Failed request: (409) Conflict: an artifact with this name already exists on the workflow runDiagnose it: was the cache hit, and was it the right one?
Cache bugs split into three shapes and they need different fixes: the cache never saved, it saved but the key never matches on restore, or it restored a stale entry through a restore-keys prefix and is now poisoning the build. The step output tells you which one you have.
- uses: actions/cache@v4
id: cache
with:
path: ~/.npm
key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-npm-
- name: What happened
run: |
echo "exact hit: ${{ steps.cache.outputs.cache-hit }}"
echo "key used: ${{ steps.cache.outputs.cache-matched-key }}"Common causes
Same artifact name across a matrix
In v4 each artifact name must be unique within a run. Every matrix leg uploading name: build overwrites is not allowed - the second one conflicts.
Re-uploading the same name in one run
Unlike v3, v4 does not merge multiple uploads into one artifact. A second upload of the same name in the same run is a conflict.
How to fix it
Give each upload a unique name
Incorporate the matrix value (or job context) into the artifact name so every leg is distinct.
- uses: actions/upload-artifact@v4
with:
name: build-${{ matrix.os }}-${{ matrix.node }}
path: dist/Merge later if you need one artifact
- Upload uniquely named artifacts per leg, then combine them in a later job.
- Use actions/upload-artifact/merge@v4 to merge them into a single artifact.
- Or download all and re-upload one consolidated artifact.
Cache limits that produce confusing failures
- Repository cache is capped at 10 GB. Past that, GitHub evicts least-recently-used entries, so a large cache can silently stop persisting.
- Caches are scoped by branch. A cache written on a feature branch is not visible to another feature branch, only to its base and its own descendants.
- An entry not read for 7 days is evicted, so a rarely-run workflow effectively never has a warm cache.
- Restoring a cache built for a different tool version is worse than a cold start, because you get a corrupted tree instead of a clean install. Always include the tool version in the key.
How to prevent it
- Make v4 artifact names unique per matrix leg.
- Use the merge action when a single combined artifact is needed.
- Remember v4 artifacts are immutable - no re-upload to the same name.