GitHub Actions "Failed to download artifact" / artifact not found

By Kaveh Alemi·Latchkey

download-artifact looked for an artifact by name in the current run and found nothing, almost always because the upload was skipped, the names differ, or it lives in a different run.

What this error means

The download step fails with "Failed to download artifact" or that no artifact matching the name was found, and the consuming job cannot proceed.

Error: Failed to download artifact: Unable to find an artifact with the name: build-output

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

Upload skipped or name mismatch

The producing job did not upload (it failed or was skipped) or used a different artifact name than the download expects.

Artifact is in another run

The artifact was created in a separate workflow run, so the same-run lookup finds nothing without cross-run configuration.

How to fix it

Match names and ordering

1. Use identical name on upload-artifact and download-artifact.
2. Ensure the producing job ran and succeeded before the consumer (needs:).
3. For cross-run downloads, set run-id and a token.

- uses: actions/download-artifact@v4
  with:
    name: build-output

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

• Keep upload/download artifact names in sync.
• Order producing and consuming jobs with needs:.
• Confirm the upload step actually ran.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions