GitHub Actions "an artifact with this name already exists" - overwrite

By Kaveh Alemi·Latchkey

In artifact v4, names are immutable and unique within a run. A second upload with the same name fails unless you choose a unique name or pass overwrite: true.

What this error means

A second upload-artifact step (often in a matrix that reuses one name) fails saying the artifact name already exists, so the later upload is lost.

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

Diagnose 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

Reusing one name across matrix jobs

Every matrix combination uploading under the same name collides because v4 artifact names must be unique per run.

Re-uploading to replace contents

Unlike v3, v4 will not silently overwrite. Replacing an artifact requires the overwrite flag.

How to fix it

Use a unique name per upload

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

Or set overwrite when replacing

When you intentionally want to replace an artifact, opt in explicitly.

- uses: actions/upload-artifact@v4
  with:
    name: report
    path: report/
    overwrite: true

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

• Give every artifact a unique name, especially in a matrix.
• Use overwrite: true only for intentional single replacements.
• Merge per-matrix artifacts into one with upload-artifact/merge.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions