Rules TOML enforces that other formats do not
TOML looks like INI, but it is strictly typed and much less forgiving. Five rules account for most failures:
- Strings must be quoted.
url = postgres://localhost/shopis an error; writeurl = "postgres://localhost/shop". Single quotes create literal strings where backslashes are not escapes, which is the easy way to write Windows paths. - Booleans are lowercase.
TrueandFALSEare invalid values; onlytrueandfalsework. - Keys and tables can be defined only once. Repeating
namein[package], opening[server]twice, or settinga.b = 1and thena = 2are all redefinitions. - One key-value pair per line. Anything after the value other than a comment is an error.
- Dates and times must be real.
2026-13-45is not a date, and the validator says so instead of storing it as text.
Arrays of tables ([[bin]]) add another trap: after [[products]], writing a plain [products] header is a redefinition, not a new section.
How it validates and reports
Validation uses smol-toml, a small spec-compliant parser, and layout uses taplo compiled to WebAssembly. The parser stops at the first problem; the editor highlights that line, and the formatted output from the last valid version stays on screen, greyed out, while you edit. Messages are the parser’s own, such as “Trying to redefine an already defined table or value”, paired with a precise line and column. That column matters: for a duplicated table header it points into the header, not at the key that collides with it.
Once the file passes, the Tree view shows the data the way a TOML library will load it. That is the quickest way to confirm that a dotted key such as tool.ruff.line-length ended up nested where you meant it to be.
Things a TOML validator cannot judge
The check is about TOML syntax and types, not about what Cargo, Poetry, uv or Hugo expect. A misspelled [dependancies] section is valid TOML; Cargo will only warn about an unused manifest key when it builds. Version requirement strings like "^1.0" are not interpreted, and inline tables are not compared with any schema. For pyproject.toml, tools such as validate-pyproject check the packaging metadata itself.
Spec versions are a second blind spot. smol-toml implements TOML 1.1.0, which relaxed a few rules: inline tables may now span several lines and end with a trailing comma, and the seconds in a time value became optional. Every TOML 1.0 file is still valid, but the reverse is not true. If the consuming tool pins an older parser, keep inline tables such as serde = { version = "1.0", features = ["derive"] } on a single line to stay portable.
Everything happens in your browser. Manifests often reference private registries or include tokens in URLs, and none of that is sent anywhere when you validate.
Examples
Package name defined twice
Invalid: name already exists in [package], so the second definition on line 5 is rejected.
[package]
name = "shop-api"
version = "0.3.1"
edition = "2021"
name = "shop-server"
Line 5, column 1: Trying to redefine an already defined table or valueUnquoted connection string
Invalid: TOML has no bare strings, so the value must be wrapped in quotes.
[database]
url = postgres://localhost:5432/shop
pool_size = 10
Line 2, column 7: Invalid valueTable header opened twice
Invalid: [server] cannot be reopened later in the file; move timeout into the first [server] table.
[server]
host = "0.0.0.0"
port = 8080
[logging]
level = "info"
[server]
timeout = 30
Line 8, column 2: Trying to redefine an already defined table or valueA valid pyproject.toml excerpt
Passes validation; the Tree view shows tool.ruff nested under tool.
[project]
name = "orders"
version = "1.4.0"
requires-python = ">=3.11"
dependencies = ["httpx>=0.27", "pydantic>=2"]
[tool.ruff]
line-length = 100
[project]
name = "orders"
version = "1.4.0"
requires-python = ">=3.11"
dependencies = ["httpx>=0.27", "pydantic>=2"]
[tool.ruff]
line-length = 100
Common errors and how to fix them
| Error | Cause | Fix |
|---|---|---|
Trying to redefine an already defined table or valueExplained | A key, table header or dotted key path was defined a second time. | Merge the two definitions into one place, or rename the duplicate key. |
Invalid value | The value is not a TOML type: usually an unquoted string or a capitalised True or False. | Quote strings and write booleans in lowercase. |
Each key-value declaration must be followed by an end-of-line | Extra text follows a value on the same line, such as a second value or a comment without #. | Put each key on its own line and start comments with #. |
Illegal character in key | A table header is missing its closing bracket, so the parser reads the rest of the line as a key. | Close the header with ] and check the key for spaces or symbols that need quoting. |
Frequently asked questions
Which TOML version is supported?
The parser implements TOML 1.1.0, which is backward compatible with 1.0.0. A file that relies on 1.1 additions, such as an inline table split across lines, passes here but can fail in a tool that only supports 1.0.
Why is my duplicate table an error when INI allows it?
TOML maps every file to a single unambiguous data structure, so reopening a table or redefining a key is forbidden by the specification.
Does it check Cargo.toml dependency versions?
No. It confirms the file is valid TOML. Version requirements and feature names are checked by Cargo when you build.
How do I write a Windows path in TOML?
Use a literal string with single quotes, such as path = ‘C:\Users\aisha’, where backslashes are not escape characters.