Skip to content

xtr_dotenv.exception

Every error this library raises.

All of them derive from :class:DotenvError, so one except catches anything a layered dotenv load can go wrong with, and a narrower one handles one cause. Each carries the data a caller needs as typed attributes rather than forcing a message to be parsed.

DotenvError

Bases: Exception

Base class for every error raised by this library.

Catch this to handle anything a layered dotenv load can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.

FormatError

FormatError(path: str, line: int, reason: str)

Bases: DotenvError, ValueError

A line in a dotenv file the parser could not read.

Raised where the bad line lives — a bad binding, or a key without = — rather than pretending the file loaded and letting a caller trip over a value that is not there.

Also a :class:ValueError, so code already guarding parsing with except ValueError keeps working without learning a new exception.

Attributes:

  • path (str) –

    The file the line came from, as it was given to the loader.

  • line (int) –

    The 1-based line number in path.

  • reason (str) –

    What about the line could not be read.

Record where the bad line is, and why it could not be read.

InvalidArgumentError

InvalidArgumentError(reason: str)

Bases: DotenvError, ValueError

A loader or its configuration was given a value it cannot work with.

Also a :class:ValueError, so code that already guards its configuration with except ValueError keeps working without learning a new exception.

Attributes:

  • reason (str) –

    What is wrong with the value.

Record what is wrong with the value.

PathError

PathError(path: str)

Bases: DotenvError, OSError

A file a loader was told to read, or a command to write, but could not.

Raised where the work was asked for, so a missing file, a directory in its place, a permission error, or a symbolic link where a real file belongs fail loudly and where the caller can do something about it — not silently as a file with nothing in it.

Also an :class:OSError, so code catching filesystem failures keeps working.

Attributes:

  • path (str) –

    The file that could not be used.

Record the path that could not be used.

VariableCircularReferenceError

VariableCircularReferenceError(names: tuple[str, ...])

Bases: DotenvError, ValueError

Variables that reference each other, and never resolve.

Expansion repeats while each pass resolves something; values still unresolved once a pass resolves nothing wait on each other, and are treated as a cycle rather than left with a suspicious empty value.

Attributes:

  • names (tuple[str, ...]) –

    The variable names still unresolved after the final pass.

Record the variables that never resolved.