How to fix yaml: line X: found character that cannot start any token in Docker

DockerBEGINNERMEDIUMUpdated Dec 1, 2025· 272 views

This YAML parsing error occurs when your docker-compose.yml file contains tab characters for indentation. YAML strictly forbids tabs and requires spaces. The fix is simple: replace all tabs with spaces (typically 2 spaces per indent level).

Quick fix

Fixes yaml: line X: found character that cannot start any token

docker compose config
  1. Identify the problematic line
  2. Find all tabs in your file
  3. Replace tabs with spaces automatically
  4. Fix tabs using sed (alternative method)
docker — error
docker compose config
yaml: line X: found character that cannot start any token

What this error means

When Docker Compose parses your `docker-compose.yml` file, it uses a YAML parser that enforces the YAML specification strictly. One of YAML's fundamental rules is that **tab characters are not allowed for indentation**—only spaces are permitted. The error "found character that cannot start any token" is the YAML parser's way of saying it encountered an unexpected character (the tab) where it expected valid YAML syntax. The full error typically looks like: ``` yaml.scanner.ScannerError: while scanning for the next token found character '\t' that cannot start any token ``` This rule exists because different editors and systems interpret tab width differently (some use 2 spaces, others 4 or 8). Since YAML relies heavily on indentation to define structure, allowing tabs would lead to inconsistent parsing across different environments.

Typical symptoms

  • Running 'docker-compose up' or 'docker-compose config' fails with a YAML parsing error
  • Error message mentions 'found character that cannot start any token'
  • Error message may show '\t' as the problematic character
  • The error points to a specific line number in your docker-compose.yml
  • File looks correctly indented visually but still fails to parse
  • Error appeared after copying YAML from a website or IDE that uses tabs

Common causes

  1. Tab characters used for indentation instead of spaces
  2. Mixed tabs and spaces in the indentation
  3. YAML copied from IDEs that auto-insert tabs (like IntelliJ)
  4. Text copied from websites or documentation that used tabs
  5. Editor configured to insert tabs when pressing the Tab key
  6. File edited in different editors with inconsistent tab/space settings

How to fix "yaml: line X: found character that cannot start any token"

1Identify the problematic line

The error message tells you which line contains the tab character. Run:

bash
docker compose config

Look for output like:

bash
yaml: line 12: found character that cannot start any token

This tells you line 12 contains a tab character.

2Find all tabs in your file

Use grep to find all lines containing tab characters:

bash
grep -n $'\t' docker-compose.yml

This will show line numbers and content of any lines with tabs. If you see output, those lines need to be fixed.

Alternatively, check the entire file for tabs:

bash
cat -A docker-compose.yml | head -20

Tabs will appear as ^I in the output.

3Replace tabs with spaces automatically

Use the expand command to convert all tabs to spaces:

bash
# Convert tabs to 2 spaces and save to new file
expand -t 2 docker-compose.yml > docker-compose.yml.fixed

# Verify the fix worked
docker compose -f docker-compose.yml.fixed config

# Replace original file
mv docker-compose.yml.fixed docker-compose.yml

Or do it in one line (be careful—this modifies the file in place):

bash
expand -t 2 docker-compose.yml > /tmp/compose.yml && mv /tmp/compose.yml docker-compose.yml
4Fix tabs using sed (alternative method)

If expand isn't available, use sed to replace tabs with spaces:

bash
# Replace each tab with 2 spaces
sed -i 's/\t/  /g' docker-compose.yml

On macOS, use:

bash
sed -i '' 's/\t/  /g' docker-compose.yml
5Configure your editor to use spaces

Prevent this issue from recurring by configuring your editor:

VS Code:
1. Open Settings (Ctrl/Cmd + ,)
2. Search for "Insert Spaces"
3. Enable "Editor: Insert Spaces"
4. Set "Editor: Tab Size" to 2
5. Use "Convert Indentation to Spaces" from Command Palette (Ctrl/Cmd + Shift + P)

Vim:
Add to your ~/.vimrc:

vim
set expandtab
set tabstop=2
set shiftwidth=2

IntelliJ/WebStorm:
1. Go to Settings > Editor > Code Style > YAML
2. Set "Tab size" and "Indent" to 2
3. Check "Use tab character" is DISABLED

6Enable visible whitespace in your editor

Make tabs visible to catch them before they cause errors:

VS Code:
1. Open Settings
2. Search for "Render Whitespace"
3. Set to "all" or "boundary"
4. Tabs will appear as arrows (→), spaces as dots (·)

Sublime Text:
Add to Preferences:

json
{
  "draw_white_space": "all"
}

This helps you immediately spot when tabs sneak into your YAML files.

7Validate your YAML with an online parser

If you're still having issues, paste your YAML into an online validator:

- [YAML Lint](http://www.yamllint.com/)
- [YAML Online Parser](http://yaml-online-parser.appspot.com/)

These tools will highlight exactly where the syntax errors are and often provide more descriptive error messages than Docker Compose.

Advanced notes

Why YAML forbids tabs: The YAML specification explicitly prohibits tabs for indentation because different systems interpret tab width differently. What looks like valid 2-level nesting in one editor might be interpreted completely differently in another. Since YAML's structure depends entirely on indentation, this ambiguity would cause silent parsing bugs.

Git pre-commit hooks: Add a pre-commit hook to catch tabs before they're committed:

bash
#!/bin/bash
# .git/hooks/pre-commit
if grep -r $'\t' --include="*.yml" --include="*.yaml" .; then
  echo "ERROR: Tab characters found in YAML files"
  exit 1
fi

EditorConfig for teams: Create an .editorconfig file in your project root to enforce consistent settings across all team members' editors:

ini
# .editorconfig
root = true

[*.{yml,yaml}]
indent_style = space
indent_size = 2

Docker Compose JSON mode exception: Technically, when using JSON-compatible flow style in YAML (with braces and brackets), tabs are valid within quoted strings. However, Docker Compose's parser may still reject them. It's safest to avoid tabs entirely in docker-compose files.

CI/CD validation: Add YAML linting to your CI pipeline:

yaml
# In your CI config
- name: Lint YAML files
  run: |
    pip install yamllint
    yamllint docker-compose.yml

Frequently asked questions

What does "yaml: line X: found character that cannot start any token" mean?
yml file, it uses a YAML parser that enforces the YAML specification strictly. One of YAML's fundamental rules is that tab characters are not allowed for indentation—only spaces are permitted. The error "found character that cannot start any token" is the YAML parser's way of saying it encountered an unexpected character (the tab) where it expected valid YAML syntax.
How do I fix "yaml: line X: found character that cannot start any token"?
This YAML parsing error occurs when your docker-compose.yml file contains tab characters for indentation. YAML strictly forbids tabs and requires spaces. The fix is simple: replace all tabs with spaces (typically 2 spaces per indent level).
What causes "yaml: line X: found character that cannot start any token"?
Tab characters used for indentation instead of spaces Mixed tabs and spaces in the indentation YAML copied from IDEs that auto-insert tabs (like IntelliJ)
Is the "yaml: line X: found character that cannot start any token" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading