GitHub Actions actions/upload-pages-artifact "missing artifact"

By Kaveh Alemi·Latchkey

actions/deploy-pages consumes a specially-named artifact produced by actions/upload-pages-artifact. If that upload step did not run, or its path matched nothing, the deploy step has no Pages artifact to publish.

What this error means

A deploy-pages step fails saying no Pages artifact was found, usually because the upload step was skipped, failed, or had an empty path.

Error: No artifact named 'github-pages' found for this workflow run.
Ensure a Pages artifact was uploaded with actions/upload-pages-artifact.

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 step skipped or failed

A job ordering or conditional issue meant upload-pages-artifact never produced the artifact.

Empty publish path

upload-pages-artifact path pointed at a directory with no built files.

How to fix it

Build, upload, then deploy

1. Run the site build and confirm it produces files.
2. Use actions/upload-pages-artifact with the correct path.
3. Keep build job and deploy job dependency (needs:) correct.

- uses: actions/upload-pages-artifact@v3
  with:
    path: ./dist
- uses: actions/deploy-pages@v4

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 exists before uploading the Pages artifact.
• Keep needs: ordering between build and deploy jobs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions