GitHub Actions "No files were found" - actions/upload-artifact v4 Failures

By Kaveh Alemi·Latchkey

actions/upload-artifact failed because the path matched no files, the working directory was wrong, or (in v4) an artifact with that name already exists in the run.

What this error means

The upload step warns "No files were found with the provided path" and produces an empty or missing artifact, or in v4 fails because the artifact name was already uploaded in the same run.

Actions log

Warning: No files were found with the provided path: dist/.
No artifacts will be uploaded.
# or (v4)
Error: Failed to CreateArtifact: an artifact with this name already exists

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.

.github/workflows/ci.yml

- 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

Path matches no files

The path is wrong relative to the working directory, the build did not produce output, or a prior step ran in a different directory.

v4 immutable, unique-name artifacts

upload-artifact@v4 creates immutable artifacts and rejects a duplicate name within the same run, unlike v3 which merged uploads.

How to fix it

Point at the real output path

Confirm the build emitted files and use a path relative to the job working directory.

.github/workflows/ci.yml

- run: npm run build   # produces ./dist
- uses: actions/upload-artifact@v4
  with:
    name: site
    path: dist
    if-no-files-found: error

Give each v4 artifact a unique name

Suffix names with the matrix value, for example name: logs-${{ matrix.os }}.
Do not upload the same artifact name twice in one run under v4.
Set if-no-files-found: error so an empty match fails loudly instead of silently.

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

Verify the build output path before the upload step.
Use unique artifact names per matrix leg under v4.
Set if-no-files-found: error to catch empty uploads early.

Frequently asked questions

What causes GitHub Actions "No files were found"?

There are 2 common causes: path matches no files and v4 immutable, unique-name artifacts. The path is wrong relative to the working directory, the build did not produce output, or a prior step ran in a different directory.

How do I fix GitHub Actions "No files were found"?

There are 2 fixes depending on which cause you have: point at the real output path and give each v4 artifact a unique name. Work through them in order, since the first is the most common.

What does GitHub Actions "No files were found" actually mean?