OptixLog Docs
Concepts

Error Model

The OptixLog exception hierarchy — OptixLogError, AuthenticationError, NotFoundError, MultipleResultsError, ValidationError — and when each is raised.

All OptixLog SDK exceptions inherit from OptixLogError. Catching OptixLogError catches every SDK-level error; catch the subclasses for targeted handling.

Exception hierarchy

OptixLogError
├── AuthenticationError   — invalid or missing API key
├── NotFoundError         — get(id) found nothing, or one() found zero
├── MultipleResultsError  — one() found more than one result
└── ValidationError       — server rejected the ingest payload

# Additional errors for CLI and credential paths:
OptixLogError
├── CredentialsError      — credentials file missing, corrupt, or incomplete
├── ConfigError           — optixlog.toml missing, corrupt, or invalid
└── ContractError         — schema fixture or server response violates the contract

All of these are importable from optixlog:

from optixlog import (
    OptixLogError,
    AuthenticationError,
    NotFoundError,
    MultipleResultsError,
    ValidationError,
)

OptixLogError

The base class for all SDK errors. Catch this to handle any SDK-level failure without distinguishing the cause.

from optixlog import OptixLogError

try:
    result = client.project(Projects.GRATING_COUPLER_LAB).ingest(
        data=sim_node,
        prompt="FDTD run.",
    )
except OptixLogError as e:
    print(f"SDK error: {e}")

AuthenticationError

Raised when the API key is invalid, expired, or missing, and the server rejects the request.

When it occurs:

  • You pass an invalid key to SDKClient or OptixClient.
  • Your stored key has been revoked.
  • The key lacks permission for the operation you are attempting.
from optixlog import AuthenticationError

try:
    config = project.config.get()
except AuthenticationError:
    print("API key is invalid or expired — run optixlog login to refresh.")

NotFoundError

Raised when a strict lookup finds nothing.

When it occurs:

  • collection.get(id) — no item with that ID.
  • collection.one(**filters) — no items match the filters.
from optixlog import NotFoundError

try:
    team = project.teams.get("nonexistent-team-id")
except NotFoundError:
    print("Team not found.")

try:
    event = project.audit_events.one(request_id="unknown-request-id")
except NotFoundError:
    print("No audit event with that request ID.")

Use get_or_none(id) or first(**filters) when zero results should not raise.

MultipleResultsError

Raised when one(**filters) finds more than one matching item.

When it occurs:

  • collection.one(**filters) — more than one item matches.
from optixlog import MultipleResultsError

try:
    team = project.teams.one(category="engineering")
except MultipleResultsError:
    print("Multiple engineering teams exist — narrow your filters.")

ValidationError

Raised when the server rejects an ingest payload because the data violates the project's schema.

When it occurs:

  • pipeline_project.ingest(...) — the payload fails server-side schema validation (e.g. a required field is missing, a value is the wrong type, or an enum value is not in the allowed set).
from optixlog import ValidationError

try:
    result = project.ingest(data=node, prompt="sim run")
except ValidationError as e:
    print(f"Payload rejected: {e}")

Static vs runtime validation

The generated typed bindings catch many schema violations at type-check time (pyright/mypy), before you run your code. ValidationError covers cases that slip through — for example, wrong values in Mapping[str, JSONValue] fields that are dynamically populated at runtime.

CredentialsError

Raised when the credentials file is missing, unreadable, or lacks the required api_base_url and api_key fields for the requested profile. Primarily encountered in CLI commands.

ConfigError

Raised when optixlog.toml cannot be found (walking up from cwd), cannot be parsed, or is missing required fields. Primarily encountered by optixlog generate and optixlog init.

ContractError

Raised during code generation when the schema (from the server or a fixture) violates the expected structure — for example, an unknown project ID in project_node_types, conflicting field definitions for a shared node type, or an unsupported schema_version.

Handling errors in practice

from optixlog import (
    AuthenticationError,
    NotFoundError,
    MultipleResultsError,
    ValidationError,
    OptixLogError,
)

try:
    result = client.project(Projects.GRATING_COUPLER_LAB).ingest(
        data=sim_node,
        prompt="FDTD run.",
    )
except AuthenticationError:
    # Refresh credentials and retry, or abort.
    raise
except ValidationError as e:
    # Log the error and skip this node.
    print(f"Skipping invalid payload: {e}")
except OptixLogError as e:
    # Unexpected SDK error — log and reraise.
    print(f"Unexpected error: {e}")
    raise

See Lookup Patterns for when NotFoundError and MultipleResultsError are raised by collection methods. See API Reference — Errors for the full reference.

Lookup Patterns

When to use get vs get_or_none vs one vs first vs count vs iter — exact raise semantics and when each is appropriate.

Python SDK

Overview of the OptixLog Python SDK — install, import map, and navigation to the Management, Pipeline, and generated-bindings APIs.

On this page

Exception hierarchyOptixLogErrorAuthenticationErrorNotFoundErrorMultipleResultsErrorValidationErrorCredentialsErrorConfigErrorContractErrorHandling errors in practice