YAML fails on tabs because the spec forbids tab characters in indentation, so a parser stops as soon as a line starts with a tab. Replace every leading tab with spaces, keep sibling keys at the same number of spaces, and set your editor to insert spaces when you press Tab. Tabs elsewhere in a line are allowed by the spec, but not every parser accepts them.
What the YAML spec says about tabs
The YAML spec bans tabs only in indentation. Section 6.1 of the YAML 1.2.2 specification says: "To maintain portability, tab characters must not be used in indentation, since different systems treat tabs differently."
Indentation is how YAML decides which key belongs to which parent. If one editor shows a tab as two columns and another shows it as eight, the same file has two different structures. Spaces remove that guess.
The ban is narrow. Section 6.2 says that between tokens within a line, white space "may safely include tab characters." The grammar defines white space as a space or a tab. So a tab between a key's colon and its value is legal YAML, even if your parser disagrees.
Why YAML tabs were dropped
YAML's authors tried to support tabs and gave up. On js-yaml issue #80, one of YAML's creators wrote that the team "spent every day for 3 months (circa 2003) trying to sanely allow tabs into YAML indentation," and concluded it "was an insane endeavor."
The same comment states the rule parsers should follow: an error should happen when tabs are detected "in a place where indentation might occur." That issue was about js-yaml accepting tabs when it shouldn't. It was closed on Dec 30, 2020, after a fix that throws tab characters must not be used in indentation (2:1).
The errors you will see
The tab error message depends on which parser reads your file. Here is the same tab-indented file in the two parsers I tested:
server:
host: localhost
- PyYAML 6.0.3:
while scanning for the next token found character '\t' that cannot start any token, at line 2, column 1. - js-yaml 4.1.0:
tab characters must not be used in indentation (2:1).
The js-yaml message names the problem. The PyYAML one doesn't, which is why the Home Assistant FAQ has a page for that exact message. Its answer: a tab was used instead of two spaces.
Tab-indented list items ( - a) fail the same way, at line 2, column 1, in both parsers.
Where PyYAML and js-yaml disagree on tabs
PyYAML 6.0.3 rejects tabs in places the spec allows, and js-yaml 4.1.0 accepts them. I ran the same small snippets through both parsers:
| Snippet | PyYAML 6.0.3 | js-yaml 4.1.0 |
|---|---|---|
Tab after a colon: key:<tab>value |
error, line 1, column 5 | loads {key: value} |
Tab inside a value: msg: hello<tab>world |
error, line 1, column 11 | loads hello<tab>world |
Tab after a list dash: -<tab>one |
error, line 2, column 4 | loads ["one"] |
Tab inside a | block scalar |
loads, tab kept | loads, tab kept |
| Tab as indentation | error | error |
A config file can load in a Node.js tool and fail in a Python one. One tab pasted into a value, say from a spreadsheet, does it. If a file must work in both, treat every tab outside a block scalar as a bug.
The block scalar row is the safe exception. Inside script: |, the tab is content, not indentation, so both parsers keep it in the string.
How to find and replace tabs in a YAML file
Search the file for tab characters, then replace each leading tab with spaces. On Linux or macOS, this lists every line with a tab and its line number:
grep -n "$(printf '\t')" config.yaml
Then fix them:
- Replace each leading tab with spaces, matching the indentation of the sibling keys.
- Check any tab in the middle of a line. If you need PyYAML to read the file, change it to a space or quote the value.
- Leave tabs inside
|or>block scalars alone if they are meant to be content. - Load the file again with the parser your tool uses.
How many spaces? Any consistent number works. Two is the usual choice, and it is what the Home Assistant FAQ and the Salt docs recommend.
Stop your editor from adding tabs
Set your editor to insert spaces when you press the Tab key. The YAML spec itself points out that most modern editors can be configured that way. In Vim, the Salt docs suggest :set tabstop=2 expandtab and then :retab, which also converts the tabs already in the file.
The Salt docs put the rule bluntly: "YAML uses spaces, period." I'd add one thing: turn on visible whitespace for YAML files. A tab and two spaces look identical until the parser complains.
This only fixes your copy of the file. If a tool or a teammate's editor keeps writing tabs back in, the error returns, so the editor setting matters more than the one-time cleanup.
A tab is also not the only invisible YAML trap. A colon inside a value causes the "mapping values are not allowed here" error, and unquoted no becomes a boolean in the YAML Norway problem. If you are still choosing a config format, JSON vs YAML for config files compares the trade-offs, and YAML vs YML settles the extension question.
FAQ
Can you use tabs in YAML at all?
Yes, outside indentation. The YAML 1.2.2 spec allows tabs as white space between tokens on a line and inside scalar content. They are only banned as indentation. Some parsers, such as PyYAML, are stricter than the spec.
What does found character '\t' that cannot start any token mean?
It is the PyYAML error for a tab in a place the scanner does not accept. Most often a line is indented with a tab. Replace the tab with spaces and the error goes away.
How many spaces should replace a tab in YAML?
Any consistent number works, as long as sibling keys line up. Two spaces is the common choice, and it is what the Home Assistant and Salt docs suggest.
Why did the YAML authors ban tabs?
Different systems treat tabs differently, so a tab-indented file could mean different things in different editors. One of YAML's creators says the team spent three months around 2003 trying to allow tabs and gave up.