actions/configure-pages "Pages site failed" - Enable & Fix

By Kaveh Alemi·Latchkey

actions/configure-pages cannot prepare the Pages deployment because Pages is not enabled with GitHub Actions as the source, or the job lacks the permissions Pages deployment needs.

What this error means

The configure-pages step fails saying it could not get or create the Pages site, often with a 404 or "Pages site failed". The deploy never proceeds because the site is not configured for Actions.

Actions log

Error: Get Pages site failed. Please verify that the repository has Pages
enabled and configured to build using GitHub Actions
HttpError: Not Found

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

Pages not set to the Actions source

In repo Settings > Pages, the build source must be "GitHub Actions". If Pages is disabled or set to a branch, configure-pages cannot find a site to configure.

Missing Pages permissions

Pages deployment needs pages: write and id-token: write on the job. Without them the configure/deploy steps cannot operate on the site.

How to fix it

Enable Pages with the Actions source and set permissions

.github/workflows/pages.yml

permissions:
  pages: write
  id-token: write
  contents: read
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/configure-pages@v5

Verify the repo Pages setting

Settings > Pages > Build and deployment > Source = GitHub Actions.
Confirm the repository has Pages available for its visibility/plan.
Pair configure-pages with upload-pages-artifact and deploy-pages in the same workflow.

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

Set the Pages source to GitHub Actions before running the workflow.
Declare pages: write and id-token: write for Pages jobs.
Keep configure/upload/deploy Pages actions on compatible versions.

Frequently asked questions

What causes actions/configure-pages "Pages site failed"?

There are 2 common causes: pages not set to the actions source and missing pages permissions. In repo Settings > Pages, the build source must be "GitHub Actions".

How do I fix actions/configure-pages "Pages site failed"?

There are 2 fixes depending on which cause you have: enable pages with the actions source and set permissions and verify the repo pages setting. Work through them in order, since the first is the most common.

What does actions/configure-pages "Pages site failed" actually mean?

The configure-pages step fails saying it could not get or create the Pages site, often with a 404 or "Pages site failed".

How do I stop actions/configure-pages "Pages site failed" happening again?

Set the Pages source to GitHub Actions before running the workflow. The prevention section lists 3 changes that keep it from recurring.