Invalid TOML? Fix pyproject.toml & Cargo.toml Errors
Short answer: invalid TOML is usually a quick fix. Paste your file into the TOML Validator. It checks the syntax against TOML 1.0 (or 1.1), shows the exact line and column of each problem, the surrounding lines, what is wrong and how to fix it. Nothing leaves your browser.
What TOML is
TOML ("Tom's Obvious, Minimal Language") is a configuration file format designed to be easy to read and unambiguous to parse. It is the standard format for Python's pyproject.toml, Rust's Cargo.toml, and many other tools such as Hugo, Deno and Starship.
A short example:
# comment
title = "Example" # key = value
site.name = "demo" # dotted key
[server] # table
host = "localhost"
ports = [8080, 8081] # array
limits = { cpu = 2, mem = 512 } # inline table
[[routes]] # array of tables
path = "/health"
[[routes]]
path = "/items"
Key rules: keys are case-sensitive; one key = value pair per line; # starts a comment outside a string; strings, integers, floats, booleans, dates/times, arrays and inline tables are the value types; there is no null.
Why validating matters
A single wrong character can stop a build, a package install or a deployment. Tools often show a cryptic message such as "expected newline" or "invalid TOML". A validator tells you the exact position and the rule you broke, before you commit or publish.
TOML vs YAML vs JSON
| TOML | YAML | JSON | |
|---|---|---|---|
| Comments | Yes | Yes | No |
| Indentation matters | No | Yes | No |
| Null value | No | Yes | Yes |
| Native dates | Yes | Yes (version-dependent) | No |
| Best for | Simple, explicit config | Complex nested data | Data exchange |
TOML avoids YAML's indentation traps (see how YAML converts to JSON), which is why it is popular for package configuration. If you work with both, see YAML syntax errors and how to fix them.
The most common TOML errors
These messages come from the validator, so you can match what you see:
| Broken TOML | Mistake | Fix |
|---|---|---|
host = localhost |
Text without quotes | Quote it: host = "localhost" |
enabled = True |
Capitalised boolean | Use lowercase true / false |
name: "demo" |
Colon instead of = |
Use name = "demo" |
price = 1,000 |
Comma inside a number | Use 1000 or 1_000 |
| Same key twice | Duplicate key | Keep one; keys must be unique in a table |
[server] twice |
Duplicate table | Merge into one table |
a = 01 |
Leading zero in integer | Write 1 |
Missing closing ] |
Unclosed array | Close it (the error often shows on the next line) |
Reading the error position
The line and column show where the parser could no longer continue. The mistake is usually on that line, but not always. A missing closing ] is only noticed on the next line, and an unterminated multi-line string is only noticed at the end of the file. That is why the tool shows the lines around the error.
How to find an invalid TOML error with the TOML Validator
- Open the TOML Validator.
- Choose TOML 1.0 (default) or TOML 1.1.
- Paste your TOML, or open a
.tomlfile. - Read the Problems found list. Each problem has a line and column, a few surrounding lines with a marker under the exact position, a plain-language explanation, a category (key, string, number, date or time, array, inline table, table header, duplicate or conflicting definition, or syntax), and a button that selects the line in the editor.
- Fix from the top, then check again. The parser stops at the first error, so the tool skips the broken line and checks the rest, reporting up to 10 problems. Later problems can be a consequence of earlier ones, and the tool marks them when that is likely.
- When the document is valid, you get a summary (keys, tables, arrays of tables, value types, nesting depth) and an outline of its tables.
- To see the parsed values as JSON, use the TOML to JSON Converter.
Large documents are checked in a background worker so the page stays responsive.
Using it with pyproject.toml and Cargo.toml
- pyproject.toml: check the syntax before running
pip installor publishing. A typo in[project]or[build-system]will stop a build. - Cargo.toml: check dependency tables such as
[dependencies]and[dev-dependencies], and any inline tables likeserde = { version = "1", features = ["derive"] }.
Limits to know
- This is a syntax check. A file can be valid TOML and still be wrong for its tool, for example an unknown key in
pyproject.tomlor a missing required field inCargo.toml. Those tools do their own validation. - Lines skipped after the first error are not checked, so one fix may reveal more problems.
- Suggested fixes appear only for a few unambiguous cases (unquoted text, a capitalised boolean, a colon instead of an equals sign, a comma inside a number) and are never applied automatically.
- The checker supports TOML 1.0 and 1.1 as the selector offers. Check which version your tool expects, because some parsers support only 1.0.
Frequently asked questions
How do I validate TOML online? Paste it into the TOML Validator and read the problems list.
Why does TOML say "duplicate key"? TOML forbids defining the same key twice in one table, and forbids defining the same table header twice.
Can TOML store null? No. Leave the key out, or use an agreed placeholder value.
What is the difference between [table] and [[table]]?
[table] defines one table. [[table]] defines an array of tables, adding one more entry each time it appears.
Is it safe to paste my config? The validator runs locally and nothing is sent to a server. Still, remove real secrets from any config before sharing it anywhere (see the Secret Scanner, and what to do if a key has already leaked).
Related tools and guides
- TOML to JSON Converter
- YAML Validator and YAML ⇄ JSON Converter
- JSON Schema Validator to validate the shape of converted data
- .env ⇄ JSON Converter
- YAML syntax errors guide