What causes "bad expression, please check expression syntax" in mikefarah/yq?

Join intended multiple results with a comma: `.a, .b`

bad expression, please check expression syntax

Error message

bad expression, please check expression syntax

What it means

After reducing all postfix operations, createExpressionTree expects exactly one expression node on the stack. More than one (or zero) leftover nodes means the token stream does not form a single well-formed expression, so compilation fails with this generic message.

Source

Thrown at pkg/yqlib/expression_parser.go:86

				stack = remaining
			case 2:
				if len(stack) < 2 {
					return nil, fmt.Errorf("'%v' expects 2 args but there is %v", strings.TrimSpace(Operation.StringValue), len(stack))
				}
				remaining, lhs, rhs := stack[:len(stack)-2], stack[len(stack)-2], stack[len(stack)-1]
				newNode.LHS = lhs
				lhs.Parent = &newNode

				newNode.RHS = rhs
				rhs.Parent = &newNode

				stack = remaining
			}
		}
		stack = append(stack, &newNode)
	}
	if len(stack) != 1 {
		return nil, fmt.Errorf("bad expression, please check expression syntax")
	}
	return stack[0], nil
}

View on GitHub (pinned to 8b5af0694b)

Solutions

Join intended multiple results with a comma: `.a, .b`
Split into separate expressions with multiple -e flags or multiple yq invocations
Remove stray tokens/characters; validate the expression in an interactive yq first

Example fix

// before
yq '.a .b' file.yml   # bad expression, please check expression syntax
// after
yq '.a, .b' file.yml

Defensive patterns

Strategy: validation

Validate before calling

// reject juxtaposed expressions like '.a .b'
if matched, _ := regexp.MatchString(`\S\s+\.`, expr); matched {
    // could be '.a, .b' intended
    if !strings.Contains(expr, ",") {
        return fmt.Errorf("multiple paths must be comma-separated: %q", expr)
    }
}

Try / catch

out, err := runYq(expr, file)
if err != nil && strings.Contains(err.Error(), "bad expression, please check expression syntax") {
    return fmt.Errorf("invalid yq expression %q", expr)
}

Prevention

Separate multiple results with commas: `.a, .b`
Avoid pasting two expressions into one invocation; use -e or separate calls
Lint generated expressions with a quick `yq --version`-safe dry run before production use

When it happens

Trigger: Expressions with juxtaposed expressions separated incorrectly, e.g. `yq '.a .b'` (two independent results, no operator), stray commas/brackets, or an expression like `yq 'a b c'` that leaves multiple nodes.

Common situations: Mixing multiple expressions without a comma in select/update contexts, accidentally pasting two commands into one -e-less expression, leftover characters from editing.

Related errors

AI-assisted analysis of mikefarah/yq@8b5af0694b (2026-09-05). Data as JSON: /api/errors/d42ff4a959d74658. Report an issue: GitHub.