A YAML file cannot contain tabs as indentation

A YAML file cannot contain tabs as indentation

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

A YAML file cannot contain tabs as indentation

You encounter this error message—A YAML file cannot contain tabs as indentation—when your text editor or IDE has inadvertently mixed tab characters with spaces while defining a mapping structure. This is a fundamental rule of the YAML specification, not a quirk specific to Symfony 2 routing files. When you paste code from one environment to another, or switch between different keyboard layouts, it is surprisingly easy to introduce invisible tab characters that break parsers expecting strict consistency.

In the context of your Symfony application, the error points directly to your routing.yml file (or the equivalent route definition in newer versions). YAML relies on whitespace for structural integrity. It treats indentation as a delimiter that defines nesting levels, much like how braces {} define scope in other languages. However, unlike many other programming languages where spaces and tabs might be treated interchangeably by compilers, the YAML spec explicitly forbids mixing them within the same document block.

When you see the error log stating that your routing file is invalid, it usually means one of two things:

  1. You are using a tab key to indent lines inside the defaults block or the route definition itself.
  2. Your text editor's "Convert Indentation on Save" feature failed to normalize the file before you committed it to version control.

Consider the structure of a valid YAML mapping. Every level of nesting must be indented by exactly two spaces relative to its parent. If you hit the Tab key while editing, most modern editors will visually render that indentation as 2 or 4 spaces, but the actual character stored in the file remains a horizontal tab (\t). When the Symfony router attempts to parse this configuration, it reads the stream and immediately flags the presence of a tab character where only spaces are permitted. This is a safety mechanism to prevent ambiguity; if tabs were allowed alongside spaces, a block indented by 2 spaces followed by one indented by a tab (which equals 4 spaces) could lead to misaligned keys that are visually correct but structurally wrong.

To resolve this, you must ensure the file contains only space characters for indentation. The most reliable way to fix this without manually hunting through lines in an editor is to use your terminal's sed command or a dedicated linting tool. For instance, running sed -i 's/\t/ /g' routing.yml on a Linux system will globally replace every tab character with two spaces. On macOS, the equivalent command requires the -E flag for extended regex: sed -i '' -E 's/\t/ /g' routing.yml.

Alternatively, configure your editor to "Insert Spaces" instead of tabs. In Visual Studio Code or Sublime Text, this is often a setting in user preferences (editor.insertSpaces). Once enabled, the editor will automatically convert any tab keystrokes into spaces before they are written to the disk. This prevents the issue from recurring during future edits.

While debugging routing issues, it is also worth checking that the syntax inside the defaults block matches the expected format. In Symfony 2, you might define routes like this:

community_online_shop_homepage:
    pattern: /
    defaults: { _controller: CommunityOnlineShopBundle:Page:index }
_login:
    pattern: /login
    defaults: { _controller: CommunityOnlineShopBundle:Page:login}

If the parser complains about indentation here, look closely at the line containing _controller. If that key is indented with a tab instead of spaces relative to defaults, the file becomes invalid. The solution remains consistent regardless of the specific route: sanitize the whitespace.

For developers working across different environments, relying on strict YAML validation tools like yamllint can prevent these headaches before they cause deployment failures. Integrating such a tool into your workflow ensures that no tab characters slip through the cracks, keeping your configuration files robust and predictable.

Our network