🚨 Filebeat Error Guide: 'error loading config file ... yaml: line X' — Fix YAML Syntax Errors

Overview

Filebeat refuses to start and exits immediately when its configuration file is not valid YAML. The message points at a line and a parser reason:

Exiting: error loading config file: yaml: line 24: mapping values are not allowed in this context

Filebeat parses filebeat.yml (and any files it includes) as YAML before doing anything else. If the YAML is malformed — a tab instead of spaces, a misaligned key, an unquoted value containing a colon — the parse fails and Filebeat aborts with a yaml: line X error. The line number is where the parser detected the problem, which is frequently one or two lines after the real mistake (a common YAML gotcha), so you must inspect the surrounding block, not only the named line.

Symptoms

• Filebeat exits at startup; systemctl status filebeat shows a failed start, not a running service.
• The log line begins with Exiting: error loading config file: and ends with yaml: line X: ....
• The reason is one of mapping values are not allowed, did not find expected key, found character that cannot start any token, or could not find expected ':'.
• The config worked before a recent edit.
• found character that cannot start any token almost always means a literal tab character.

Common Root Causes

• Tabs used for indentation — YAML forbids tabs; only spaces are allowed.
• Inconsistent indentation — a key indented one space off from its siblings.
• Unquoted value containing a colon — e.g. pattern: ^\d{2}:\d{2} or a Windows path C:\logs.
• A missing space after a colon — key:value instead of key: value.
• Mixing list (-) and map indentation incorrectly under filebeat.inputs.

Diagnostic Workflow

Validate YAML shape first, then narrow to the offending block around the reported line.

filebeat test config -c /etc/filebeat/filebeat.yml    # prints the yaml: line X error
sed -n '18,30p' /etc/filebeat/filebeat.yml            # view around the reported line
grep -nP '\t' /etc/filebeat/filebeat.yml               # find literal tabs (a top cause)

Confirm with an independent YAML parser to cross-check the line and reason:

python3 -c "import yaml,sys; yaml.safe_load(open('/etc/filebeat/filebeat.yml'))"

A correctly-indented input block for comparison — spaces only, quoted specials:

# /etc/filebeat/filebeat.yml
filebeat.inputs:
  - type: filestream
    id: app
    paths:
      - /var/log/app/*.log
    parsers:
      - multiline:
          type: pattern
          pattern: '^\d{4}-\d{2}-\d{2}'   # quoted: contains no bare colon issues
          negate: true
          match: after

Example Root Cause Analysis

An engineer added a multiline timestamp pattern and pasted it unquoted:

- multiline:
    pattern: ^\d{2}:\d{2}:\d{2}      # BUG: unquoted, contains colons
    negate: true

Filebeat exited with yaml: line 27: mapping values are not allowed in this context. The YAML parser saw the colons inside the timestamp regex as map separators. The reported line 27 was actually the line after the pattern — a classic off-by-one. Quoting the value resolved it:

    pattern: '^\d{2}:\d{2}:\d{2}'

The lesson: any scalar containing : (regex, timestamps, Windows paths, URLs) must be single-quoted, and the error line is a hint, not an exact address.

Prevention Best Practices

• Configure your editor to insert spaces, never tabs, and to show whitespace for YAML files.
• Always single-quote scalars that contain :, #, {, [, *, or backslashes (regexes, paths, timestamps).
• Keep indentation consistent — two spaces per level is the Elastic convention.
• Run filebeat test config in CI and as a pre-commit check so malformed YAML never deploys.
• When the reported line looks fine, inspect the line above it — YAML often reports the error one line late.

Quick Command Reference

filebeat test config                       # report yaml: line X error
grep -nP '\t' /etc/filebeat/filebeat.yml    # find forbidden tabs
sed -n '18,30p' filebeat.yml               # inspect around the reported line
python3 -c "import yaml;yaml.safe_load(open('filebeat.yml'))"   # cross-check parser
# fix: quote colons/backslashes, use spaces not tabs, align indentation

Conclusion

error loading config file ... yaml: line X is a pure YAML syntax failure that stops Filebeat before it does any work. The most common causes are tabs, misaligned indentation, and unquoted values containing colons. Use filebeat test config and a second YAML parser to confirm, remember the error line is often one line late, and quote any scalar with special characters. Wiring filebeat test config into CI keeps broken YAML out of production entirely.