# Troubleshooting

## `BudgetExceeded`

Inspect `item_costs`, `overflow_tokens`, `exceeded_at_item_id`, `available_strategies`, and `partial_manifest`. Increase the budget, explicitly demote content after authorization, opt into safe Text truncation, or reject the model call. See {doc}`overflow`.

## `PolicyViolation`

Inspect `rule_id`, `reason_code`, `item_id`, and `boundary`. Required items raise where optional items would be excluded. Do not catch the exception and resend the same item through a less strict boundary without an application authorization decision.

## `UnsupportedContent`

Binary is storage and round-trip only in the 0.1 series. Optional/preferred Binary items appear in manifest exclusions; required Binary items raise during packing. Convert content only through an application-approved process or keep it outside the pack.

## `SchemaError`

Common causes include:

- empty IDs when constructing `ContextItem` directly;
- a supplied `content_hash` that does not match canonical content;
- a negative `min_tokens`;
- timezone-naive datetime objects passed directly to `ContextItem`;
- running an AI operation after `select()` or aggregation removed `id` or `payload`.

Use `collect_records()` rather than `collect()` for exploratory tables that are no longer valid context items.

## `PluginError`

Rankers must return one numeric score per item. Python tokenizers must return one non-negative integer per input string. Change a plugin fingerprint whenever its results can change.

## Approximate token counts

`profiles.approximate()` is always estimated. Binary wheels contain the native Rust tokenizers for `o200k_base` and `cl100k_base`, but `profiles.openai()` still reports `estimated=True` because its provider envelope cost is conservative. The Python `tokenizers` extra is not required for those native paths.

## Missing Arrow, pandas, or Polars

Install only the integration you need, for example:

```bash
uv add "cognoxium[arrow]"
```

or:

```bash
python -m pip install "cognoxium[arrow]"
```

## Unexpectedly selected untrusted content

`untrusted` is a label, not an automatic block. External packing requires provenance but otherwise allows it. Use `quarantine()` or a custom policy as shown in {doc}`boundaries`.

## Different manifests across runs

Supply stable `id` and `created_at` fields, preserve input order, pin the Cognoxium version, use the same token-profile fingerprint, and pin plugin configuration. Defaults use a UUID and current time.