Errors - Cirron Documentation

All SDK exceptions derive from CirronError, which derives from Exception. Import from the top-level package:

from cirron import (
    CirronError,
    CirronDependencyError,
    CirronSecretNotFound,
    CirronYamlError,
)

The data loader adds three more. They’re raised by ci.load() but not exported from the top-level namespace today; import from cirron.core.errors if you need to catch them by class:

from cirron.core.errors import (
    CirronDatasetNotFound,
    CirronPlatformRequired,
    CirronDataSizeError,
)

Hierarchy

Exception
└── CirronError
    ├── CirronDependencyError
    ├── CirronSecretNotFound
    ├── CirronYamlError
    ├── CirronDatasetNotFound
    ├── CirronPlatformRequired
    └── CirronDataSizeError

Catch CirronError to handle any SDK-raised exception.

`CirronError`

Base class. Rarely raised directly; catch it at the top level when you want one handler for every SDK-originated failure.

try:
    df = ci.load(...)
except CirronError as e:
    log.error("SDK failure", exc_info=e)

`CirronDependencyError`

Raised when a required optional extra isn’t installed. The message includes the pip install hint. Typical triggers:

ci.load(as_="polars") without cirron-sdk[polars]
ci.load(as_="hf") without cirron-sdk[hf]
ci.load("postgres://...") without cirron-sdk[postgres]
Framework autodetect asked for tensorflow hooks but TF isn’t importable
ci.deps("torch", "pandas") with either extra missing: the fail-fast form lists every missing dep in one error with a combined install command

Handling:

try:
    df = ci.load("./events.parquet", as_="polars")
except CirronDependencyError as e:
    print(e)     # includes the install hint
    df = ci.load("./events.parquet")   # fall back to pandas

Prefer failing at startup. When you know which extras a script needs, call ci.deps at the top so missing extras raise immediately rather than 40 minutes into training:

ci.deps("torch", "pandas", "transformers")

`CirronSecretNotFound`

Raised by ci.secret(name) when neither the CIRRON_SECRET_<NAME> env var nor the /etc/cirron/secrets/<name> file mount is present. Message points at the platform’s secrets UI. Handling:

try:
    key = ci.secret("openai-api-key")
except CirronSecretNotFound:
    key = os.environ.get("OPENAI_API_KEY")   # local-dev fallback
    if not key:
        raise

`CirronYamlError`

Raised when a cirron.yaml file fails to parse or fails Pydantic validation. Message includes the file path and the validation error chain.

`CirronDatasetNotFound`

Raised by ci.load(..., source="platform") when the registered dataset or bucket name doesn’t resolve. Message includes the name that was requested and a hint to check the platform dashboard.

`CirronPlatformRequired`

Raised by ci.load(..., source="platform") when credentials or network connectivity aren’t available: either the process lacks a CIRRON_API_KEY, the resolve endpoint is unreachable, or the workspace ID isn’t set. Message includes an actionable fallback suggestion (usually: switch to an explicit URI, or run cirron login).

`CirronDataSizeError`

Raised by ci.load() when the matched bytes across all sources meet or exceed load_max_bytes (10 GB default) and confirm_large=False. Message includes the estimated size and narrowing hints. Bypass when you mean it:

df = ci.load("s3://huge-bucket/", confirm_large=True)

Or raise the threshold:

from cirron import Cirron
c = Cirron(load_max_bytes=50_000_000_000)   # 50 GB
df = c.load("s3://huge-bucket/")

`NotImplementedError`

ci.load(..., search=..., top_k=...) raises the stdlib NotImplementedError, not a Cirron-specific exception. The parameters are accepted for API stability but the platform vector-index backing them hasn’t shipped yet. Once it does, the NotImplementedError is replaced by normal return behavior; no API break for callers already passing the kwargs.

What never raises

By design, these paths log warnings and continue rather than raise:

Framework hook callbacks that fail internally: logged at WARNING, training continues.
The flush thread encountering a transient network error: exponential backoff, eventually degrades to spool-only mode.
The spool filling disk: oldest batch files are evicted, drop counter increments.

The SDK never crashes your training or serving loop.

Types

Non-error types: Profiler, CirronYaml, LazyHandle.

ci.load errors

Same exceptions, scoped to the loader.

​Hierarchy

​CirronError

​CirronDependencyError

​CirronSecretNotFound

​CirronYamlError

​CirronDatasetNotFound

​CirronPlatformRequired

​CirronDataSizeError

​NotImplementedError

​What never raises

​Related