Home / GitHub Actions / GitHub Actions Workflow Parse Error Because YAML Mapping Values Are Not Allowed

GitHub Actions

GitHub Actions Workflow Parse Error Because YAML Mapping Values Are Not Allowed

Fix GitHub Actions workflow YAML parse errors such as `mapping values are not allowed here` by correcting indentation, multi-line `run` blocks, and unquoted values with special characters.

Published: Jan 22, 20269 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

Introduction

GitHub Actions workflows are defined in YAML files, a human-readable configuration format that uses indentation and specific syntax rules to define structure. When a workflow file contains YAML syntax errors, GitHub's parser fails before any workflow execution begins. The error message "mapping values are not allowed here" is one of the most common YAML parse errors, indicating that the parser encountered a colon (:) in an unexpected context.

This error typically results from incorrect indentation, missing colons after keys, improperly formatted multi-line strings, or unquoted values containing special characters. The reported line number often points to where the parser failed, not where the actual mistake was made—the real error may be several lines earlier where the structure first became invalid.

Understanding YAML syntax rules—especially indentation, key-value pairs, multi-line blocks, and quoting— is essential for writing valid GitHub Actions workflows and debugging parse errors efficiently.

Symptoms

When GitHub Actions workflow YAML has mapping values errors, you will observe these symptoms:

GitHub shows workflow as invalid before any job starts
Error message references "mapping values are not allowed here"
Workflow list shows error indicator next to workflow name
Recent edits to the workflow preceded the error
The same workflow worked before a formatting change
Error appears in multiple places if indentation cascades incorrectly

GitHub UI error display:

``` Invalid workflow file Error: .github/workflows/ci.yml line 45: mapping values are not allowed here

Workflow validation failed ```

GitHub API error response:

json

{
  "message": "Invalid workflow file: .github/workflows/ci.yml",
  "errors": [{
    "path": ".github/workflows/ci.yml",
    "message": "mapping values are not allowed here",
    "line": 45
  }]
}

CLI error when pushing:

bash

git push
remote: Resolving deltas: 100% (15/15), completed with 5 local objects.
remote: error: GH-EE: Invalid workflow file
remote: error: .github/workflows/ci.yml - mapping values are not allowed here on line 45

Common Causes

Several factors cause YAML "mapping values are not allowed" errors:

1.Missing colon after key: YAML keys must be followed by a colon and space. Missing the colon causes the next line to be misinterpreted.
2.Incorrect indentation: YAML uses consistent indentation to define structure. Misaligned lines break the nesting hierarchy.
3.Multi-line run without pipe character: Multi-line shell commands under run: must use the pipe character (|) to indicate a literal block scalar.
4.Unquoted values with special characters: Values containing colons, brackets, braces, or other YAML-significant characters must be quoted.
5.Tabs instead of spaces: YAML forbids tabs for indentation. Using tabs causes parsing failures.
6.Trailing spaces or invisible characters: Invisible characters can break YAML parsing in subtle ways.
7.Incorrect list syntax: Missing hyphen for list items or incorrect list formatting causes structure errors.
8.Nested structure errors: Incorrect nesting of keys under wrong parents shifts the entire structure.

Step-by-Step Fix

Follow these steps to diagnose and resolve YAML mapping values errors:

Step 1: Locate the error line

Identify the reported error location:

```bash # View the workflow file around the error line sed -n '40,50p' .github/workflows/ci.yml

# Or with line numbers cat -n .github/workflows/ci.yml | sed -n '40,50p'

# GitHub often reports the line where parsing failed # The actual mistake may be earlier ```

Step 2: Check for missing colons

Verify all keys have proper colon syntax:

```yaml # WRONG: Missing colon after name - name Build run: npm test

# CORRECT: Colon after name key - name: Build run: npm test

# WRONG: Missing colon after step type - uses actions/checkout@v4

# CORRECT: Colon after uses key - uses: actions/checkout@v4 ```

Step 3: Verify indentation is consistent

Check indentation alignment:

```yaml # WRONG: Inconsistent indentation jobs: build: runs-on: ubuntu-latest # Wrong: 3 spaces steps: # Wrong: 4 spaces but inconsistent - uses: actions/checkout@v4

# CORRECT: Consistent 2-space indentation jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

# Check for mixed tabs and spaces cat -A .github/workflows/ci.yml | grep -E '\^I' # Shows tabs as ^I ```

Step 4: Fix multi-line run blocks

Use proper block scalar syntax:

```yaml # WRONG: Multi-line without pipe - name: Build run: npm ci npm run build npm test

# CORRECT: Multi-line with pipe - name: Build run: | npm ci npm run build npm test

# WRONG: Inline continuation - name: Deploy run: npm run build npm run deploy

# CORRECT: Block scalar or single line - name: Deploy run: npm run build && npm run deploy

# Or: - name: Deploy run: | npm run build npm run deploy ```

Step 5: Quote values with special characters

Add quotes around problematic values:

```yaml # WRONG: Unquoted colon in value env: MESSAGE: Hello: World

# CORRECT: Quoted colon value env: MESSAGE: "Hello: World"

# WRONG: Unquoted brackets run: echo [test]

# CORRECT: Quoted brackets run: echo "[test]"

# WRONG: Unquoted URL with port url: http://localhost:3000/api

# CORRECT: Quoted URL (or accept that YAML parses correctly here) url: "http://localhost:3000/api"

# Common values needing quotes: # - URLs with ports (http://host:port) # - Time expressions (30s, 5m) # - Version strings with dashes (v1.0-beta) # - Strings starting with special characters ```

Step 6: Verify list syntax

Check list item formatting:

```yaml # WRONG: Missing hyphen for list item steps: uses: actions/checkout@v4 run: npm test

# CORRECT: Hyphen for each list item steps: - uses: actions/checkout@v4 - run: npm test

# WRONG: Nested list incorrect matrix: include: node: 18 os: ubuntu-latest

# CORRECT: Proper list structure matrix: include: - node: 18 os: ubuntu-latest ```

Step 7: Use YAML validation tools

Validate the workflow locally:

```bash # Install actionlint (recommended) # macOS: brew install actionlint

# Linux: bash -c "$(curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)"

# Validate workflow actionlint .github/workflows/ci.yml

# Output with specific errors: ci.yml:45:3: "mapping values are not allowed here" could not find expected ':'

# Use yq for YAML validation yq . .github/workflows/ci.yml

# Use Python YAML parser python3 -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml'))" ```

Step 8: Compare with working version

If the workflow worked before:

```bash # Show diff with last working version git diff HEAD~5 HEAD -- .github/workflows/ci.yml

# View previous working version git show HEAD~5:.github/workflows/ci.yml

# Find when it broke with git bisect git bisect start git bisect bad HEAD git bisect good HEAD~10 # Then test each commit ```

Step 9: Fix and re-validate

Apply fixes and validate:

```yaml # Example corrected workflow name: CI on: push: branches: [main]

jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4

name: Setup Node
uses: actions/setup-node@v4
with:
node-version: "20"

name: Install and Test
run: |
npm ci
npm run build
npm test
env:
NODE_ENV: "test"
API_URL: "https://api.example.com:443"
`

```bash # Validate after fixes actionlint .github/workflows/ci.yml

# Should output nothing if valid ```

Verification

After fixing YAML errors, verify the workflow is valid:

```bash # Validate with actionlint actionlint .github/workflows/ci.yml # Expected: No output (no errors)

# Push and check GitHub response git add .github/workflows/ci.yml git commit -m "fix: correct YAML syntax" git push

# Check workflow appears without error indicator gh workflow list

# Trigger workflow to confirm it runs gh workflow run ci.yml gh run watch ```

Check GitHub UI:

bash

Actions > Workflows > CI
Status: No validation errors

Prevention

To prevent YAML mapping values errors:

1.Use a YAML-aware editor: Configure your editor with YAML linting.

json

// VS Code settings.json
{
  "yaml.validate": true,
  "editor.formatOnSave": true,
  "[yaml]": {
    "editor.defaultFormatter": "redhat.vscode-yaml"
  }
}

1.Always use spaces, never tabs: Configure editor to use spaces.

json

// Editor config
{
  "editor.insertSpaces": true,
  "editor.tabSize": 2
}

1.**Use run: | for multi-line commands**: Consistent pattern for blocks.

yaml

# Always use pipe for multi-line
run: |
  command1
  command2

1.Quote values with special characters: When in doubt, quote.

yaml

env:
  URL: "https://api.example.com:443"
  VERSION: "1.0.0-beta"

1.Validate before committing: Use pre-commit hooks.

yaml

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rhysd/actionlint
    rev: v1.6.26
    hooks:
      - id: actionlint

1.Use actionlint in CI: Add validation to your pipeline.

yaml

- name: Validate workflows
  run: actionlint .github/workflows/*.yml

1.Keep a template workflow: Use a known-good workflow as starting point.

```yaml # Save as workflow-template.yml name: Template on: push: branches: [main]

jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: echo "Template workflow" ```

[WordPress troubleshooting: Fix IAM Access Denied 403 - Complete Tro](fix-iam-access-denied-403)
[GitHub Actions Artifact Expired or 403 Download Failed](github-actions-artifact-expired-403-download-failed)
[Fix Github Actions Artifact Upload Failed File Too Large 5gb Limit Issue in GitHub Actions](github-actions-artifact-upload-failed-file-too-large-5gb-limit)
[Fix Github Actions Aws S3 Deploy Credentials Expired Rotate Issue in GitHub Actions](github-actions-aws-s3-deploy-credentials-expired-rotate)
[Fix Github Actions Cache Evicted Manually Workflow Fails Download Issue in GitHub Actions](github-actions-cache-evicted-manually-workflow-fails-download)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

GitHub Actions Workflow Parse Error GitHub Actions Workflow Parse Error GitHub Actions GitHub Actions Workflow Parse Error troubleshooting GitHub Actions Workflow Parse Error fix Fix GitHub Actions workflow YAML parse errors such as `mapping values are not allowed here` by correcting indentation, multi-line `run` blocks, and unquoted values with special characters GitHub Actions Fix GitHub Actions workflow YAML parse errors such as `mapping values are not allowed here` by correcting indentation, multi-line `run` blocks, and unquoted values with special characters

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

GitHub Actions Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this github-actions-errors troubleshooting guide applies to my situation?

This guide is designed for github-actions-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these github-actions-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of github-actions-errors issue?

Most github-actions-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this github-actions-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for github-actions-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Jan 22, 2026

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation

GitHub Actions Workflow Parse Error Because YAML Mapping Values Are Not Allowed

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Locate the error line

Step 2: Check for missing colons

Step 3: Verify indentation is consistent

Step 4: Fix multi-line run blocks

Step 5: Quote values with special characters

Step 6: Verify list syntax

Step 7: Use YAML validation tools

Step 8: Compare with working version

Step 9: Fix and re-validate

Verification

Prevention

People also search for

Browse Guides from Other Categories

WordPress

SSL

DNS

GitHub Actions Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading

GitHub Actions Workflow Parse Error Because YAML Mapping Values Are Not Allowed

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Locate the error line

Step 2: Check for missing colons

Step 3: Verify indentation is consistent

Step 4: Fix multi-line run blocks

Step 5: Quote values with special characters

Step 6: Verify list syntax

Step 7: Use YAML validation tools

Step 8: Compare with working version

Step 9: Fix and re-validate

Verification

Prevention

Related Articles

People also search for

Share this guide

More GitHub Actions Troubleshooting Guides

Browse Guides from Other Categories

GitHub Actions Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading