🚨 yq Error: 'bad file: mapping values are not allowed in this context' — Cause, Fix, and Troubleshooting Guide

Overview

yq fails before it can evaluate your expression because the file it was handed is not valid YAML. The mapping values are not allowed in this context message comes from the underlying YAML parser: it found a : (a mapping indicator) in a place where a mapping cannot start — almost always an unquoted colon inside a scalar value, a bad indentation level, or a tab character where spaces are required.

This is the mikefarah yq (the Go implementation, v4). The error is fatal and points at a line number:

$ yq e '.server.url' config.yaml
Error: bad file 'config.yaml': yaml: line 7: mapping values are not allowed in this context

The line number is where the parser gave up, which is often one line after the real mistake. Because the file never parses, no expression runs — a yq '.' identity read fails exactly the same way, which is the fastest way to confirm the problem is the file and not your query.

Symptoms

• yq exits non-zero with bad file '<name>': yaml: line N: mapping values are not allowed in this context.
• The same file fails even with a trivial expression like yq e '.' config.yaml.
• yamllint config.yaml reports a syntax error at or just before the same line.
• A CI step that reads config with yq breaks after an edit that “looked fine.”
• The file loads fine in one tool but not yq, or vice-versa (a sign you are running a different yq than you think).

# Identity read reproduces it without any expression
yq e '.' config.yaml

Error: bad file 'config.yaml': yaml: line 7: mapping values are not allowed in this context

Common Root Causes

1. Unquoted colon in a scalar value

The most common cause. A value that contains : (colon-space) is parsed as a nested mapping key, which is illegal mid-scalar.

server:
  url: http://example.com:8080
  note: see runbook: escalate to on-call

note: see runbook: escalate has a second : the parser treats as a new mapping — quote the value.

2. Bad indentation

A key indented to a level that does not line up with its siblings, or a mapping started under a scalar.

service:
  name: orders
   port: 8080

port is indented one extra space and no longer belongs to the same mapping as name.

3. A tab character instead of spaces

YAML forbids tabs for indentation. A tab pasted from another editor produces the same class of parse failure.

grep -nP '\t' config.yaml

7:	port: 8080

4. Wrong yq binary (Go mikefarah vs Python kislyuk)

There are two unrelated tools named yq. The Python kislyuk/yq wraps jq and uses jq syntax; the Go mikefarah/yq uses its own expression language. Running the wrong one gives confusing errors even on valid YAML.

yq --version

yq (https://github.com/mikefarah/yq/) version v4.44.3

If you see yq 3.x or a message mentioning jq, you are on the Python build and its expression syntax differs entirely.

5. File not found or wrong path

yq reports the path it was given; a typo or wrong working directory surfaces as a different error but is worth ruling out early.

6. A document-level structure error (missing value, stray ---)

A key with a trailing colon and nothing after it on a line that should have a value, or a misplaced document separator, can trip the same parser rule.

How to Diagnose

Step 1: Confirm the file, not the expression, is at fault

yq e '.' config.yaml

If the identity read fails, the file is malformed — stop debugging your query.

Step 2: Look at the reported line and the one above it

sed -n '5,9p' config.yaml | cat -A

server:$
  url: http://example.com:8080$
  note: see runbook: escalate to on-call$

cat -A shows line endings ($) and tabs (^I) so you can spot a stray tab or trailing space the parser rejected.

Step 3: Run a dedicated YAML linter for a clearer message

yamllint config.yaml

config.yaml
  7:20  error  syntax error: mapping values are not allowed here (syntax)

yamllint frequently pinpoints the column, which narrows an unquoted colon down to the exact character.

Step 4: Confirm which yq you are actually running

which -a yq && yq --version

/usr/local/bin/yq
yq (https://github.com/mikefarah/yq/) version v4.44.3

Step 5: Bisect a large file

head -n 7 config.yaml | yq e '.' -

Feeding progressively larger slices to the identity read isolates the first line that breaks parsing.

Fixes

Quote any scalar that contains a colon-space or other indicators:

  note: "see runbook: escalate to on-call"
  url: "http://example.com:8080"

Fix indentation to consistent two-space steps and strip tabs:

# Convert leading tabs to two spaces
sed -i 's/\t/  /g' config.yaml
yq e '.' config.yaml >/dev/null && echo "parses cleanly"

parses cleanly

Install and pin the correct yq. For the Go build:

# Verify you are on mikefarah v4
yq --version | grep mikefarah || echo "wrong yq — install github.com/mikefarah/yq"

Validate config files in CI before anything consumes them, so a bad edit fails loudly at lint time rather than mid-pipeline:

yamllint config.yaml && yq e '.' config.yaml >/dev/null

What to Watch Out For

• The reported line number is where parsing failed, which can be after the real mistake — always inspect the line above too.
• Two tools share the name yq; scripts written for one break silently on the other. Pin the binary and check --version in CI.
• cat -A or grep -nP '\t' catches invisible tabs and trailing whitespace that a normal editor view hides.
• Editors that auto-insert tabs (or reformat on save) reintroduce the same failure; set the project to spaces-only for YAML.
• A value that is a bare 10:30 (time-like) or 1.2.3 can be misparsed; quote ambiguous scalars deliberately.

Related Guides

• yq: bad file / YAML error deep dive is often paired with jq null iteration issues
• curl (60) SSL certificate problem — unable to get local issuer certificate
• Scheduled job orchestration at scale