GitLab Pages "pages:" path Errors - publish Folder Not Found

Newer GitLab Pages lets you set the publish directory with pages:publish instead of forcing public/. The deploy fails when that path does not exist or does not match what the build produced.

What this error means

The pages job builds fine but the Pages deploy errors or serves a 404 site, because the pages:publish directory (or public/) does not contain the built output.

Pages deploy failed: the publish directory `build` does not exist
(no files were found at pages:publish path)

Common causes

pages:publish points at the wrong directory

If you set pages:publish: build but the generator wrote to dist/, the publish path is empty and the deploy has nothing to serve.

Default public/ expected but not produced

Without pages:publish, Pages still serves public/. A build that outputs elsewhere produces an empty default path.

How to fix it

Match pages:publish to the build output

Set the publish directory to exactly where the build writes its static files.

pages:
  stage: deploy
  script:
    - npm run build   # writes to ./dist
  pages:
    publish: dist
  artifacts:
    paths:
      - dist

Verify the output and base path

1. List the build output directory in the job log to confirm it has files.
2. Make pages:publish (or the default public/) match that directory.
3. Check asset URLs resolve under the Pages base path so the deployed site does not 404.

How to prevent it

• Set pages:publish to the generator’s real output directory.
• Include the publish directory in artifacts:paths.
• Build asset URLs relative to the configured Pages base path.

Related guides