How to fix .gitlab-ci.yml: jobs:build config should be a hash in Git

What this error means

When GitLab CI parses your `.gitlab-ci.yml` file and encounters this error, it means a job definition is malformed. In YAML terminology, a "hash" (also called a mapping or dictionary) is a collection of key-value pairs. Each job in GitLab CI must be defined as a hash containing configuration options like `script`, `stage`, `image`, etc. The error typically appears when: - A job is defined as a scalar value instead of a mapping - The job name exists but has no configuration under it - YAML indentation is incorrect, causing the parser to misinterpret the structure - A job key is followed by a colon but nothing else, or followed by a list directly For example, this is invalid: ```yaml build: # Job exists but is empty or scalar # or build: "npm run build" # Scalar value instead of hash ``` The correct structure requires key-value pairs under the job name: ```yaml build: # Job name script: # Configuration key - npm run build # Configuration value ``` GitLab CI validates your YAML before running pipelines. This validation catches structural errors early, preventing failed pipeline attempts.

Typical symptoms

• Pipeline fails to start with YAML syntax error
• GitLab UI shows '.gitlab-ci.yml: jobs:build config should be a hash'
• CI/CD lint tool reports configuration error
• Pipeline status shows 'failed' immediately without running any jobs
• Merge request shows CI error before any jobs execute
• Error appears after editing .gitlab-ci.yml file

Common causes

1. Job defined as a scalar value instead of a mapping (most common)
2. Empty job definition with no configuration under it
3. Incorrect YAML indentation breaking the structure
4. Missing 'script' key or other required job configuration
5. Tabs used instead of spaces in YAML file
6. Copy-paste error introducing invisible characters
7. Job configuration placed at wrong indentation level
8. Anchor/alias YAML syntax used incorrectly

How to fix ".gitlab-ci.yml: jobs:build config should be a hash"

# Using the CI Lint endpoint
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"content": "'"$(cat .gitlab-ci.yml)"'"}' \
  "https://gitlab.com/api/v4/projects/<project_id>/ci/lint"

# If you have the gitlab-ci-local tool installed
gitlab-ci-local --lint

build: npm run build

build:
test:
  script: npm test

build:
  script:
    - npm run build

test:
  script:
    - npm test

build:
  stage: build
  image: node:18
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

build:
script:           # Should be indented
  - npm run build

build:
	script:         # Tab character (invisible problem)
		- npm run build

build:
  script:         # 2 spaces
    - npm run build

{
  "[yaml]": {
    "editor.insertSpaces": true,
    "editor.tabSize": 2,
    "editor.renderWhitespace": "all"
  }
}

jobs:             # 'jobs' is not a GitLab CI keyword
  build:
    script:
      - npm run build

stages:
  - build
  build:          # Accidentally indented under stages
    script:
      - npm run build

stages:
  - build

build:            # Job at root level
  stage: build
  script:
    - npm run build

build:
  stage: build                # Which stage to run in
  image: node:18              # Docker image to use
  variables:                  # Job-specific variables
    NODE_ENV: production
  before_script:              # Commands before main script
    - npm ci
  script:                     # Main commands (required*)
    - npm run build
  after_script:               # Commands after main script
    - echo "Build complete"
  artifacts:                  # Files to save
    paths:
      - dist/
    expire_in: 1 week
  cache:                      # Files to cache
    paths:
      - node_modules/
  rules:                      # When to run this job
    - if: $CI_COMMIT_BRANCH
  tags:                       # Runner tags
    - docker

.build_template: &build_template
  npm run build    # Scalar, not a hash

build:
  <<: *build_template

.build_template: &build_template
  image: node:18
  before_script:
    - npm ci
  script:
    - npm run build

build:
  <<: *build_template       # Merge anchor
  stage: build

build_prod:
  <<: *build_template
  stage: deploy
  script:
    - npm run build:prod    # Override script

.common:
  image: node:18
  cache:
    paths:
      - node_modules/

build:
  extends: .common          # Modern way to inherit
  script:
    - npm run build

Advanced notes

# Python
python -c "import yaml; yaml.safe_load(open('.gitlab-ci.yml'))"

# Ruby
ruby -ryaml -e "YAML.load_file('.gitlab-ci.yml')"

# Node.js (with js-yaml)
npx js-yaml .gitlab-ci.yml

include:
  - local: '/.gitlab/ci/build.yml'
  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'

trigger_child:
  trigger:
    include: child-pipeline.yml
    strategy: depend

trigger_child: child-pipeline.yml  # Invalid

{
  "yaml.schemas": {
    "https://gitlab.com/gitlab-org/gitlab/-/raw/master/app/assets/javascripts/editor/schema/ci.json": ".gitlab-ci.yml"
  }
}

jobs:
  build:
    runs-on: ubuntu-latest

build:
  image: ubuntu:latest
  script:
    - echo "building"

Frequently asked questions

What does ".gitlab-ci.yml: jobs:build config should be a hash" mean?

yml file and encounters this error, it means a job definition is malformed. In YAML terminology, a "hash" (also called a mapping or dictionary) is a collection of key-value pairs. Each job in GitLab CI must be defined as a hash containing configuration options like script, stage, image, etc.

How do I fix ".gitlab-ci.yml: jobs:build config should be a hash"?

This GitLab CI error occurs when a job in your .gitlab-ci.yml file is not properly defined as a YAML mapping (hash). The job configuration must be a key-value structure, not a scalar value or list. Fix by ensuring each job has properly indented configuration options.

What causes ".gitlab-ci.yml: jobs:build config should be a hash"?

Job defined as a scalar value instead of a mapping (most common) Empty job definition with no configuration under it Incorrect YAML indentation breaking the structure

Is the ".gitlab-ci.yml: jobs:build config should be a hash" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• remote: HTTP Basic: Access denied. The provided deploy token has expired

  How to fix 'Deploy token has expired' in GitLab

  MEDIUM

• This job is stuck because the project doesn't have any runners online

  How to fix 'This job is stuck because the project doesn't have any runners online' in GitLab CI/CD

  HIGH

• remote: GitLab: You are not allowed to force push code to a protected branch on this project

  How to fix 'not allowed to force push to a protected branch' in GitLab

  MEDIUM

• Pipeline failed: Job 'test' failed

  How to fix 'Pipeline failed: Job failed' in GitLab CI/CD

  MEDIUM

• API rate limit exceeded

  How to fix 'API rate limit exceeded' in GitHub

  MEDIUM

• fatal: destination path already exists and is not an empty directory

  Destination Path Already Exists and Is Not Empty

  LOW

Official resources & further reading

• 📚Git Official Documentation
• 📖
  GitLab CI/CD YAML syntax reference(Official Docs)
• 📖
  Optimize GitLab CI/CD configuration files(Official Docs)
• 📖
  Validate GitLab CI/CD configuration(Official Docs)
• 📖
  GitLab CI/CD Jobs(Official Docs)
• 💬
  gitlab-ci.yml jobs config should be a hash - Stack Overflow(Stack Overflow)
• 🔗
  YAML Lint - Online YAML Validator