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).
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.
The error message tells you which line contains the tab character. Run:
docker compose configLook for output like:
yaml: line 12: found character that cannot start any tokenThis tells you line 12 contains a tab character.
Use grep to find all lines containing tab characters:
grep -n $'\t' docker-compose.ymlThis 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:
cat -A docker-compose.yml | head -20Tabs will appear as ^I in the output.
Use the expand command to convert all tabs to spaces:
# 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.ymlOr do it in one line (be careful—this modifies the file in place):
expand -t 2 docker-compose.yml > /tmp/compose.yml && mv /tmp/compose.yml docker-compose.ymlIf expand isn't available, use sed to replace tabs with spaces:
# Replace each tab with 2 spaces
sed -i 's/\t/ /g' docker-compose.ymlOn macOS, use:
sed -i '' 's/\t/ /g' docker-compose.ymlPrevent 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:
set expandtab
set tabstop=2
set shiftwidth=2IntelliJ/WebStorm:
1. Go to Settings > Editor > Code Style > YAML
2. Set "Tab size" and "Indent" to 2
3. Check "Use tab character" is DISABLED
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:
{
"draw_white_space": "all"
}This helps you immediately spot when tabs sneak into your YAML files.
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.
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:
#!/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
fiEditorConfig for teams: Create an .editorconfig file in your project root to enforce consistent settings across all team members' editors:
# .editorconfig
root = true
[*.{yml,yaml}]
indent_style = space
indent_size = 2Docker 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:
# In your CI config
- name: Lint YAML files
run: |
pip install yamllint
yamllint docker-compose.ymlimage operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub