> ## 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.

# Errors

> Every exception the SDK raises and how to handle it.

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

```python theme={null}
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:

```python theme={null}
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.

```python theme={null}
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:**

```python theme={null}
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`](/sdk/reference/deps) at the top so missing
extras raise immediately rather than 40 minutes into training:

```python theme={null}
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:**

```python theme={null}
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:**

```python theme={null}
df = ci.load("s3://huge-bucket/", confirm_large=True)
```

**Or raise the threshold:**

```python theme={null}
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.

## Related

<CardGroup cols={2}>
  <Card title="Types" icon="box" href="/sdk/reference/types">
    Non-error types: `Profiler`, `CirronYaml`, `LazyHandle`.
  </Card>

  <Card title="ci.load errors" icon="database" href="/sdk/reference/load#errors">
    Same exceptions, scoped to the loader.
  </Card>
</CardGroup>