Products · Product
TOML
Raised as a usability problem by 27 people on Hacker News over 14 years (2013–2026), in 22 threads.
No issue was raised by at least 3 people in 3 threads this year.
Every issue, all time, most people first
Syntax is hard for humans to readUnreviewed
20132026- Nested TOML structure is hard to follow and errors only surface at runtime2026-09-03
- TOML table syntax is unintuitive compared to YAML's array-of-dictionary syntax2021-10-28
- Nested table structures in TOML are hard to read and understand2021-08-21
Nested structures in large config files are hard to readUnreviewed
20132026- Config file so confusing the author wrote it incorrectly2025-04-28
- Generic config formats make config files mildly irritating to wildly frustrating to use2025-04-28
- Same data has many valid representations, making round-tripping config files hard2025-02-19
Unreviewed issues were grouped by machine: Claude Haiku labelled each comment as a usability complaint, named what it's about and summed up the problem in a line, and a small model grouped similar problems. Nobody has checked them by hand. Expect mistakes.
The newest 32 complaints
- Nested TOML structure is hard to follow and errors only surface at runtime2026-09-03
- Syntax for anything beyond single-layer maps is mind-bogglingly confusing to the commenter2025-10-13
- Config file so confusing the author wrote it incorrectly2025-04-28
- Generic config formats make config files mildly irritating to wildly frustrating to use2025-04-28
- Same data has many valid representations, making round-tripping config files hard2025-02-19
- Hard to both read and write beyond the simplest cases2024-12-09
- Deeper nesting requires obscure syntax that is hard to work out2024-02-03
- Hard to understand nesting due to repeated keys and double brackets2024-01-23
- Inline tables can't span lines, so nesting becomes unwieldy beyond 80-100 characters2024-01-23
- Hard to tell at a glance whether nodes are parent, child, or sibling2023-09-21
- Nested structure in larger config files is confusing and unintuitive for humans to read2023-09-20
- Frustrating to write and read when configuration gets large and deeply nested2023-09-13
- Global versus section scoping becomes unclear once subsections are needed, and forced ordering hurts readability2023-02-10
- Hard to read and understand the structure when reading or writing it2022-08-07
- Finds TOML awful to use and dislikes being forced into it2022-08-07
- Nested arrays of objects become unreadable, so author resorts to generating it2022-05-16
- TOML table syntax is unintuitive compared to YAML's array-of-dictionary syntax2021-10-28
- Nested table structures in TOML are hard to read and understand2021-08-21
- Hard to read beyond simple unnested key-value pairs2021-07-19
- Easy to miss a nesting level, and newcomers get confused when appended lines land in the latest table2021-02-26
- Confusing and awkward past simple headers and key-values; non-obvious syntax needs mental translation2020-10-21
- Commenter finds TOML confusing and surprising, not obvious2020-09-11
- Finds the TOML configuration format harder to read and use than YAML2020-09-11
- Array of tables syntax is unintuitive and harder to write than JSON2019-08-19
- Windows paths need doubled backslashes or the config file silently breaks2019-04-14
- Nested data structures are confusing and hard to understand in TOML2018-07-14
- Can't tell what data structures TOML syntax creates without memorizing conventions2018-07-13
- TOML syntax is extremely hard to read2018-07-13
- Struggles to understand TOML syntax despite it being advertised as obvious2018-07-13
- The [[array-of-tables]] syntax is super confusing for nested arrays2018-07-13
- Array-of-tables syntax for nested arrays is super confusing to write2018-07-13
- Adding a list item forces editing the previous line, causing more merge conflicts2013-02-24