GitLab CI Troubleshooting Toolkit
Use this GitLab CI troubleshooting toolkit to diagnose failing pipelines, offline or idle runners, invalid .gitlab-ci.yml, missing CI/CD variables, cache and artifact failures, and broken deployment jobs.
Paste your error and get a triage plan.
Paste a log line, CLI error, stack trace, service failure, or config snippet and get a structured troubleshooting plan. Your snippet is carried straight into the AI Incident Response Assistant with GitLab CI context prefilled.
Do not paste secrets, tokens, private keys, passwords, or customer data. Your snippet stays in your browser until you open the assistant.
Top 25 GitLab CI Errors and Failure Modes
The production failures engineers hit most — each links to a full cause → fix → prevention guide.
Pipeline failed
A pipeline shows a red failed status when one or more jobs exit non-zero, so start by opening the first failing job's log to find the root cause.
Runner not picking up jobs
Jobs sit pending because their tags do not match any available runner or the runner is paused, so align job tags with a runner that can accept them.
Stuck job
A job hangs in running or pending state after a runner system failure or lost connection, and usually clears once the runner is restarted or the job is retried.
No runners available
The pipeline warns that this job is stuck because no runners are online to handle it, meaning you must register or unpause a runner with matching tags.
Docker executor failed
The Docker executor cannot connect to the Docker daemon, typically a Docker-in-Docker or socket configuration problem in the runner.
Shell executor failed
A shell executor job fails during setup or script execution because of missing tools, wrong permissions, or an unclean runner host environment.
Permission denied
A job aborts with permission denied when the runner user cannot read, write, or execute a path, often on the cache or working directory.
Cache upload failed
The runner cannot upload the cache archive, commonly due to permission problems or an oversized cache, leaving later jobs to rebuild from scratch.
Artifact upload failed
Artifact upload is rejected with a 413 when the archive exceeds the instance size limit, so scope paths tightly or raise the artifact limit.
Invalid .gitlab-ci.yml
The pipeline refuses to start because the CI config is syntactically or semantically invalid, which CI Lint will pinpoint line by line.
Variable not found
A referenced CI/CD variable is empty or undefined at job runtime because of scope, protection, or environment mismatches in variable hygiene.
Protected variable unavailable
A protected variable resolves to empty because the branch or tag running the job is not protected, so mark the ref protected or unprotect the variable.
Environment deployment failed
A deployment job fails during the prepare environment step, usually from a bad environment URL, missing credentials, or a broken deploy script.
Docker login failed
Authenticating to a container registry returns 401 unauthorized, meaning the token, username, or CI_JOB_TOKEN scope used for docker login is wrong.
Image pull failed
The job fails at preparation because the runner cannot pull the specified image, often from a typo, missing tag, or registry authentication issue.
Job timeout
A job is canceled after exceeding its execution timeout, so profile the slow step and raise the job or project timeout if the work is legitimately long.
Script exited with code 1
A script command returned exit code 1, which is a real command failure inside your job rather than a GitLab or runner problem.
Rules/only/except mismatch
No pipeline is created because your rules, only, or except conditions never evaluate true for the current ref or event.
Needs dependency error
A job with needs fails validation because it references a job that is not in the same pipeline or runs in a later stage.
Include file not found
The pipeline fails because an include path or remote reference cannot be resolved, so verify the file location, project, and ref.
Merge request pipeline not running
A merge request pipeline never launches because workflow rules exclude MR events or a duplicate detached pipeline rule is blocking it.
Scheduled pipeline failed
A scheduled pipeline errors or silently skips because of timezone, protected ref, or workflow rule issues in the cron configuration.
Kubernetes executor failed
A job on the Kubernetes executor fails when the build pod times out waiting to be scheduled, usually from resource limits, taints, or image pull delays.
Service container failed
A service container such as a database or sidecar fails to start or become reachable, breaking integration jobs that depend on it.
Git checkout failed
The runner cannot clone or check out the repository, commonly from access-denied job token permissions or a shallow-clone reference problem.
Validate your config before you redeploy
Catch the structural mistakes that cause outages — 100% in your browser, nothing uploaded.
Best GitLab CI Prompts
Turn symptoms, logs, and config into a structured plan with prompts tuned for GitLab CI.
Download the GitLab CI Troubleshooting Runbook Pack
Checklists for pipelines that will not run, pass, or deploy — syntax, runners, variables, and job failures.
- .gitlab-ci.yml syntax & rules checks
- Runner availability & tag matching
- CI/CD variable & masked-secret fixes
- Cache & artifact upload triage
- Job exit-code & deploy debugging
All GitLab CI Troubleshooting Guides
Grouped by failure-mode type — each guide covers cause, fix, validation, and prevention.