GitLab CI "Local file does not have project" / include not found

GitLab could not resolve an include: target. The path is wrong, the referenced project/ref does not exist, or the included file itself is invalid YAML.

What this error means

Pipeline creation fails before any job runs, naming the include it could not fetch - a missing local path, an unreachable project, or an included file that does not parse.

Pipeline Editor

Local file `ci/templates/build.yml` does not have project!
# or
Project `group/ci-templates` reference `main` does not have file `build.yml`

Common causes

Wrong local path

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

Project/ref not accessible

include:project needs the file to exist on the given ref, and the pipeline’s token must have permission to read that project. A missing ref or a private project breaks it.

Included file has invalid YAML

Even when found, the included file is parsed and merged. A syntax error there fails the whole pipeline with an include-scoped message.

How to fix it

Use the correct include form

.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 validate merged YAML

Verify the file exists on the referenced branch/tag in that project.
Ensure the project is accessible to this pipeline (group/CI job token scope).
Run the project ci/lint with include_merged_yaml=true to validate the assembled config.

How to prevent it

Pin include:project to a stable ref (tag), not a moving branch.
Keep shared templates in a project the pipeline token can read.
Lint shared templates in their own repo’s CI.