GitHub Actions upload-artifact 409: Fix “Artifact Already Exists”

Decide whether the outputs are separate or one bundle#

The right fix depends on what the artifact represents:

Do not give every parallel job name: build. The name is part of the artifact identity, so the jobs are racing to create the same object rather than appending files to a shared directory.

Give matrix jobs unique artifact names#

The most predictable matrix pattern is to include every value that changes the output:

1
jobs:
2
  build:
3
    strategy:
4
      matrix:
5
        os: [ubuntu-latest, macos-latest, windows-latest]
6
        node: [22, 24]
7
    runs-on: ${{ matrix.os }}
8
    steps:
9
      - uses: actions/checkout@v5
10
      - uses: actions/setup-node@v5
11
        with:
12
          node-version: ${{ matrix.node }}
13
      - run: npm ci
14
      - run: npm run build
15
      - uses: actions/upload-artifact@v4
16
        with:
17
          name: build-${{ matrix.os }}-node-${{ matrix.node }}
18
          path: dist/

Use the values that actually distinguish the files. If the build varies by browser, architecture, feature flag, or package, include that dimension as well. A unique name prevents a conflict, but it also makes the artifact list useful when you need to compare outputs after a failed run.

The same rule applies when the upload uses archive: false. In that mode the uploaded file’s name determines the artifact name, so two jobs can still collide even when a name input appears in the step. Make the source filenames unique or keep the default archive behavior when you need an explicit artifact name.

Merge parallel artifacts after the matrix#

If the reader of the workflow needs one artifact containing files from every matrix job, do not make the matrix jobs write to one artifact. Upload separate artifacts first, then add a dependent merge job:

1
jobs:
2
  build:
3
    strategy:
4
      matrix:
5
        platform: [linux, macos, windows]
6
    runs-on: ${{ matrix.platform }}-latest
7
    steps:
8
      - uses: actions/checkout@v5
9
      - run: ./scripts/build-${{ matrix.platform }}.sh
10
      - uses: actions/upload-artifact@v4
11
        with:
12
          name: package-${{ matrix.platform }}
13
          path: out/
14

15
  merge:
16
    needs: build
17
    runs-on: ubuntu-latest
18
    steps:
19
      - uses: actions/upload-artifact/merge@v4
20
        with:
21
          name: all-packages
22
          pattern: package-*

The merge job must wait for the matrix. That ordering turns many immutable artifacts into one new artifact without asking parallel jobs to mutate shared state. Keep the names and pattern narrow enough that an unrelated artifact from another step cannot be pulled into the bundle.

Reserve overwrite for a finished artifact#

For a sequential workflow that intentionally publishes a fresh snapshot under the same name, use overwrite: true:

1
jobs:
2
  upload-preview:
3
    needs: build
4
    runs-on: ubuntu-latest
5
    steps:
6
      - uses: actions/download-artifact@v4
7
        with:
8
          name: build-output
9
          path: preview/
10
      - uses: actions/upload-artifact@v4
11
        with:
12
          name: preview
13
          path: preview/
14
          overwrite: true

This replaces the previous artifact and creates a new artifact record. It does not merge files into the existing archive, and it is not a safe way to resolve simultaneous matrix uploads. If two jobs can reach the step at once, use unique names and a later merge instead.

Check the rendered workflow before changing the action#

When the error is not obvious, inspect the workflow as a set of jobs rather than changing action versions repeatedly:

1. Search every actions/upload-artifact step and list its final name after expression expansion.
2. Check matrix dimensions, reusable-workflow inputs, and job fan-out.
3. Look for archive: false, because the file basename may become the identity.
4. Confirm that a retry or rerun is not intentionally reusing a name that should be unique per run.
5. Decide whether a separate artifact, a merge job, or a sequential replacement matches the consumer.

If the upload then fails because a file is absent, that is a different boundary. Set if-no-files-found: error for required output and use the existing GitHub Actions hidden-files guide when dot-prefixed build files are part of the intended artifact. Do not enable hidden-file uploads merely to hide a path mistake.

The useful distinction is simple: parallel jobs should create different artifact names, a merge job should assemble a single bundle, and overwrite should replace one completed snapshot in a controlled sequence.

FAQ#