toml.errors

import toml.errors

toml lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled toml.errors.* needs import toml.errors.

Every error the toml module raises, under one root.

TomlError is that root. The three subclasses separate the cases a caller handles differently: text that is not TOML, a Zuri value that has no TOML spelling, and an edit that contradicts the document it was applied to.

Each one carries the detail a message alone cannot. ParseError knows the line and column it stopped at, EncodeError knows the type it could not write, and EditError knows the key path it could not follow.

Classes

TomlError

class toml.TomlError < Error

Base class for every error this module raises.

Catch this to catch anything toml can do.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

toml.TomlError(message)

Parameters

• message (string) — Human-readable description of the fault.

TomlError.to_string()

toml.TomlError.to_string()

ParseError

class toml.ParseError < TomlError

Text that is not valid TOML.

line and column are both 1-based and point at the character the parser gave up on, which is where the fix goes. Both are -1 when the fault belongs to the document as a whole rather than to one position in it.

import toml

catch {
  toml.parse('key = ')
} as error {
  echo '${error.line}:${error.column} ${error.message}'
}

1:7 expected a value after '='

• printable — has a @to_string(), so echo and print() show something useful

Fields

Constructor

toml.ParseError(message, line, column)

Parameters

• message (string) — Human-readable description of the fault.
• line (?number) — 1-based line, or -1 when not applicable.
• column (?number) — 1-based column, or -1 when not applicable.

ParseError.to_string()

toml.ParseError.to_string()

EncodeError

class toml.EncodeError < TomlError

A Zuri value that cannot be written as TOML.

TOML has no null, so a nil anywhere in a value raises this rather than being written as something that reads back differently. The same goes for a function, a class, a cyclic structure, and a dictionary key that is not a string.

path is the dotted key path the offending value sat at, so a rejected leaf in a deep structure can be found without a search.

• printable — has a @to_string(), so echo and print() show something useful

Fields

Constructor

toml.EncodeError(message, path)

Parameters

• message (string) — Human-readable description of the fault.
• path (?string) — Dotted key path to the offending value.

EncodeError.to_string()

toml.EncodeError.to_string()

EditError

class toml.EditError < TomlError

An edit that the document cannot accept.

Raised when a key path runs through something that is not a table, such as set('a.b', 1) on a document where a is already a string, and when a path is malformed or empty.

path is the full dotted path as it was given, so the message names what the caller asked for rather than the fragment that failed.

• printable — has a @to_string(), so echo and print() show something useful

Fields

Constructor

toml.EditError(message, path)

Parameters

• message (string) — Human-readable description of the fault.
• path (?string) — The dotted key path the edit was applied to.

EditError.to_string()

toml.EditError.to_string()

2026, Richard Ore and The Zuri Contributors