GitLab CI include File Not Found / 404

GitLab could not fetch an include: target. The local path is wrong, the referenced project/ref does not exist, or a remote URL returned 404 - so the merged config never assembles.

What this error means

Pipeline creation fails before any job runs, naming the include it could not resolve: a missing local path, an unreachable project/ref, or a 404 from a remote include.

gitlab-ci

Local file `ci/templates/build.yml` does not exist!
# or
Remote file `https://example.com/ci.yml` could not be fetched because of HTTP code 404

Common causes

Wrong local path

include:local resolves from the repository root. A wrong directory, a leading ./, or a path that exists only on another branch fails.

Project/ref not accessible or remote 404

include:project needs the file to exist on the named ref and the token to read that project; include:remote needs a reachable URL returning 200. A missing ref, a private project, or a dead URL yields a 404.

How to fix it

Use the correct include form and path

.gitlab-ci.yml

include:
  - local: 'ci/templates/build.yml'      # path from repo root
  - project: 'group/ci-templates'
    ref: main
    file: '/build.yml'

Confirm access and the ref

Verify the file exists on the referenced branch or tag in that project.
Ensure the project is readable by the pipeline (group or CI job-token scope).
For remote includes, fetch the URL manually to confirm it returns 200.

How to prevent it

Pin include:project to a stable tag, not a moving branch.
Keep shared templates in a project the pipeline token can read.
Lint shared templates in their own repository CI.