Errors

All public errors are metrana exception types — the underlying Rust engine’s own exception types never escape the API. They share a common base, so you can catch broadly or narrowly.

Initialization

Exception	Raised when
NoMetranaApiKeyError	No api_key argument and METRANA_API_KEY is unset.
MetranaLoggerInitError	The run fails to initialize — connection failure or init timeout.
MetranaRunAlreadyExistsError	Under resume_strategy="never", the run exists and can’t be confirmed to belong to this job. The message carries the run path and (when reported) the existing run’s creation time.
MetranaOrchestrationIdMismatchError	The existing run carries a different orchestration id — definitive proof it belongs to a different job launch. Subclasses MetranaRunAlreadyExistsError, so existing handlers still catch it.

import metrana
from metrana.utils.exceptions import MetranaRunAlreadyExistsError

try:
    metrana.init(workspace_name="ws", project_name="proj", run_name="run-001")
except MetranaRunAlreadyExistsError as e:
    # a different job already owns this run name
    ...

Logging & validation

Exception	Raised when
MetranaValidationError	A logged metric or attribute is rejected as invalid (bad name, scale, points, step, episode, …). Raised synchronously from the log* call — validation is the enqueue boundary.
MetranaEventQueueFullError	The send queue is full and backpressure_strategy="raise".

Delivery & shutdown

Exception	Raised when
MetranaSenderError	Surfaces accumulated background sender errors — the generic logging-runtime failure. Under delivery_policy="all_or_crash", a logger stopped by a delivery failure surfaces this on the next log / flush / close.
MetranaTimeoutError	A blocking call (e.g. flush) timed out before its data became durable. Distinct from loss — nothing was dropped; the data is still in flight, so a later flush/close (given time, ideally a disk spool) can still deliver it.
MetranaClosingError	close / shutdown_logger deadline elapsed with data still not durable (neither acknowledged nor on the spool) — likely loss.
MetranaLoggerClosedError	A call was made after the logger was closed.

Other

Exception	Raised when
MetranaNotInitializedError	A log/lifecycle call before init().
MetranaProcessForkError	A logging misuse across a fork() boundary (see Disk spool → fork).

Handling guidance

• MetranaTimeoutError is benign. Treat it as “not yet durable”, not “lost” — re-flush or close later. Pair with a disk spool and generous timeouts for strong guarantees (see Lifecycle → sizing timeouts).
• MetranaSenderError / MetranaClosingError mean likely loss. They are the loud failure the all_or_crash default is designed to produce instead of silently dropping data. A disk spool is what turns most of these into a transparent failover.
• The exception types live in metrana.utils.exceptions if you want to import and catch specific ones.