Guide

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

  1. Open the TOML Validator.
  2. Choose TOML 1.0 (default) or TOML 1.1.
  3. Paste your TOML, or open a .toml file.
  4. 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.
  5. 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.
  6. When the document is valid, you get a summary (keys, tables, arrays of tables, value types, nesting depth) and an outline of its tables.
  7. 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 install or 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 like serde = { 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.toml or a missing required field in Cargo.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

Sources and further reading