How to Debug a Failed GitLab CI Pipeline

DodaTech 2 min read

In this tutorial, you'll learn about How to Debug a Failed GitLab CI Pipeline. We cover key concepts, practical examples, and best practices.

The Problem

Your GitLab CI pipeline shows a red failed status. A job in the pipeline failed, but the error message is unclear or hidden in a wall of log output. You need to inspect the logs, reproduce the failure locally, and fix the pipeline configuration to prevent the same failure from recurring.

Quick Fix

1. View the full job log

In the GitLab UI: CI/CD > Pipelines > Click failed pipeline > Click failed job > Scroll to the bottom.

Or get the log via CLI:

# Using glab CLI
glab ci view <job-id> --log

# Or via API
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/projects/<project-id>/jobs/<job-id>/trace"

2. Enable debug logging

job-name:
  variables:
    CI_DEBUG_TRACE: "true"
  script:
    - whoami
    - pwd
    - env | sort
    - ls -la
    - # actual commands

3. Reproduce the failure locally

# Install gitlab-runner
# macO S
brew install gitlab-runner

# Linux
sudo apt-get install gitlab-runner

# Run a specific job
gitlab-runner exec docker job-name

4. Check common failure points

# Syntax errors in .gitlab-ci.yml
stages:
  - build
  - test  # ← typo: missing

# Missing dependencies — ensure package manager files exist
image: node:20
before_script:
  - npm ci  # Fails if no package-lock.json

# Branch restrictions
deploy:
  only:
    - main  # Won't run on feature branches

5. Validate the CI configuration

# Use the GitLab CI Lint API
curl --header "Content-Type: application/json" \
  "https://gitlab.com/api/v4/ci/lint?include_jobs=true" \
  --data "{'content': '$(cat .gitlab-ci.yml)'}"

Or use the GitLab UI: CI/CD > Editor > Validate tab.

6. Set variables for testing

test:
  variables:
    RAILS_ENV: "test"
    DATABASE_URL: "postgres://localhost:5432/test"
  script:
    - bundle exec rails test

7. Use rules instead of only/except

deploy:
  script: deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: always
    - when: never

Common Causes

Failure	Likely Reason	Fix
`No such file`	Missing dependency or wrong working directory	Check `before_script` for missing installs
`command not found`	Missing image or package	Use full image path or install in `before_script`
Test failures	Environment differences	Match local and CI environment
Cache not restored	Cache key changed or mismatch	Verify cache key pattern
Stage dependencies missing	Files between stages not passed via artifacts	Add `artifacts:` to the producing stage
Runner not found	No runner available for the job tag	Add tag to runner or remove tags from job

Prevention

Validate .gitlab-ci.yml with the CI Lint tool before pushing
Add `CI_DEBUG_TRACE: "true" temporarily when debugging
Use the rules: keyword instead of deprecated only:/except:

← Previous How to Fix GitLab Ci Pages Deploy Next → How to Fix GitLab Ci Registry Cleanup

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Quick Fix