GitLab CI "configuration is invalid": the common errors and fixes
Short answer
"This GitLab CI configuration is invalid" means GitLab couldn't build a pipeline from .gitlab-ci.yml, so a pushed commit gets a failed pipeline marked yaml invalid, with no jobs. The reason after the colon names the job and the problem: a misspelled keyword ("contains unknown keys"), a job without script, a script line with an unquoted colon, a stage that isn't in stages, a needs on a job that rules left out, rules mixed with only or except, a missing include, or a YAML indentation error with its line and column. Check changes in the pipeline editor, which validates as you type, or with CI Lint, which can also simulate a pipeline to catch needs and rules problems.
You push, and the pipeline fails at once with a yaml invalid badge and no jobs. Or the pipeline editor shows “This GitLab CI configuration is invalid:” followed by a reason. GitLab couldn’t build a pipeline from your .gitlab-ci.yml, and the reason says exactly where. Here are the messages GitLab 19.5 gives most often, what each means, and the fix.
Find the error
- The pipeline editor (Build › Pipeline editor) checks the file as you type. It says “Pipeline syntax is correct.” or shows the error.
- A failed pipeline with the
yaml invalidbadge shows the error on its page. - The Validate tab of the editor: Validate pipeline simulates a push of the current file, catching problems that only show when GitLab builds a pipeline, such as
needsandrules. Lint CI/CD sample opens CI Lint for any sample you paste; select Simulate a pipeline created for the default branch to simulate it too. - From a terminal,
glab ci lintsends the file to the same check.
GitLab names the place first: jobs:test is the job test, and jobs:test:script is its script. (The missing-script error is the exception: jobs test config…, with a space.)
Keywords and jobs
| GitLab says | Why | Fix |
|---|---|---|
jobs:build config contains unknown keys: artifact |
A keyword is misspelled (here artifacts), or indented under the wrong job. |
Fix the spelling or indentation; the keyword reference lists every key. |
jobs test config should implement the script:, run:, or trigger: keyword |
A job has no script, run or trigger: script is misspelled, the job is meant as a template, or a top-level keyword is misspelled, so GitLab reads it as a job. |
Fix the spelling, start a template’s name with a dot (.test-template), or add a script. |
jobs config should contain at least one visible job |
Every job is hidden, because its name starts with a dot, or the file has no jobs at all. | Add a job whose name doesn’t start with a dot. |
jobs:test config key may not be used with `rules`: only |
One job has both rules and only or except. |
Rewrite only and except as rules. |
Scripts with a colon
jobs:deploy:script config should be a string or a nested array of strings up to 10 levels deep
A script line that contains a colon and a space, like a header in a curl command, reads to YAML as a key and a value instead of a command. Quote the whole line, with single quotes outside and double quotes inside:
deploy:
script:
- 'curl --header "PRIVATE-TOKEN: $API_TOKEN" "https://gitlab.example.com/api/v4/projects"'
GitLab can also report the same mistake as “Syntax is incorrect.”
Stages and needs
test job: chosen stage tests does not exist; available stages are .pre, build, test, deploy, .post
The job’s stage isn’t in the stages list, often a typo. Without a stages list, the stages are build, test and deploy, plus .pre and .post, which always exist. Fix the name, or add the stage to stages.
'unit_tests' job needs 'compile' job, but 'compile' does not exist in the pipeline. This might be because of the only, except, or rules keywords. To need a job that sometimes does not exist in the pipeline, use needs:optional.
unit_tests lists compile under needs, but rules left compile out of this pipeline, for example because it only runs on the default branch. Make the dependency optional, or give both jobs rules that match the same pipelines:
unit_tests:
needs:
- job: compile
optional: true
YAML itself
Errors from the YAML parser name a line and a column, often after (<unknown>)::
| GitLab says | Usually |
|---|---|
did not find expected key while parsing a block mapping at line 12 column 3 |
An indentation mistake: a line indented less, or more, than the lines around it. |
mapping values are not allowed in this context at line 5 column 14 |
A colon followed by a space in a value that isn’t quoted. |
found character that cannot start any token while scanning for the next token |
A tab. YAML indents with spaces only. |
Invalid configuration format |
The file isn’t a YAML mapping at all: it’s a list or plain text, or an included URL returned a web page instead of YAML. |
Please provide content of .gitlab-ci.yml |
The file is empty. |
For mapping values… and the tab error, the problem is at the line and column named. For did not find expected key, the line named is where the surrounding block starts, often a job’s first key or line 1: look below it for a line indented differently from its neighbours.
Includes
| GitLab says | Fix |
|---|---|
Local file `templates/build.yml` does not exist! |
include:local paths start at the repository root, and the file must be on the same branch. If the file is there, retry: GitLab’s docs describe it failing now and then on clustered Gitaly setups. (A path that doesn’t end in .yml or .yaml gets Included file `…` does not have YAML extension! instead.) |
Project `group/ci-templates` file `build.yml` does not exist! |
Check the path, and the ref if you set one; a missing branch or tag gets Project `group/ci-templates` reference `v2` does not exist! |
Included file `…` is empty or does not exist! |
The included file is empty, or wasn’t found. |
Maximum of 150 nested includes are allowed! |
Too many includes, often a file that includes itself in a loop. 150 is the default; administrators of GitLab Self-Managed can raise it. |
When the pipeline doesn’t run at all
These aren’t syntax errors: the file is valid, but no job matches. On a push, GitLab simply creates no pipeline. When you start one with New pipeline or the API, it says:
- “The resulting pipeline would have been empty. Review the rules configuration.” Every job’s
rulesleft it out. - “The pipeline did not run. Review the workflow:rules configuration for the pipeline.”
workflow:rulesstopped the whole pipeline.
Before GitLab 17.3, they read “Pipeline will not run for the selected trigger” and “Pipeline filtered out by workflow rules”. Both often come from rules written for one kind of pipeline, such as merge request pipelines, being run as another: the fixes are in Pipeline will not run for the selected trigger. How the kinds differ is in GitLab merge request pipelines; skipping pipelines on purpose is in how to skip a GitLab CI pipeline.
On your phone
MergeBell shows .gitlab-ci.yml changes in merge request diffs and in the files you browse, with comments, strings and numbers coloured, so you can read a change on your phone and catch a misspelled keyword or an unquoted colon before it breaks a pipeline. Validating it, in the pipeline editor or CI Lint, needs GitLab in a browser.
Frequently asked questions
What does "This GitLab CI configuration is invalid" mean?
GitLab couldn't turn your .gitlab-ci.yml into a pipeline. The text after the colon says which job and which rule broke, such as "jobs:build config contains unknown keys: artifact". A pushed commit gets a failed pipeline with the yaml invalid badge and no jobs, and the error is on the pipeline's page and in the pipeline editor.
How do I fix "script config should be a string or a nested array of strings up to 10 levels deep"?
A line under script contains a colon followed by a space, so YAML reads it as a key and value instead of a command. Wrap the whole line in single quotes, and switch any single quotes inside it to double quotes, for example - 'curl --header "PRIVATE-TOKEN: $TOKEN" https://gitlab.example.com/api/v4/projects'.
Why does GitLab say "jobs config should contain at least one visible job"?
Every job in the configuration is hidden, because its name starts with a dot, or the file defines only stages, variables or templates. Add at least one job whose name doesn't start with a dot and that has script, run or trigger.
Why does GitLab say a job needs a job that "does not exist in the pipeline"?
The job lists another job under needs, but rules, only or except left that job out of this pipeline. Make the dependency optional with needs: [{job: build, optional: true}], or give both jobs rules that match the same pipelines.
How can I check .gitlab-ci.yml before pushing?
Open Build › Pipeline editor: it validates the file as you type and says "Pipeline syntax is correct." or shows the error. Its Validate tab simulates a pipeline from the file to catch needs and rules problems. From a terminal, glab ci lint does the same.
Sources
- GitLab docs — CI/CD YAML syntax reference
- GitLab docs — Validate GitLab CI/CD configuration (CI Lint)
- GitLab docs — Pipeline editor
- GitLab docs — Troubleshooting scripts and job logs
- GitLab docs — needs: job does not exist in the pipeline
- GitLab docs — Use CI/CD configuration from other files (include)
- GitLab source — job validation messages (jobs.rb)
- GitLab source — empty pipeline messages (has_completion_reason.rb)
Checked against these pages on 1 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.
Do this from your phone with MergeBell
Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.
Get MergeBell for iPhoneGet MergeBell for Android
On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.