Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cirron.com/llms.txt

Use this file to discover all available pages before exploring further.

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.