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 Overflow recovery.

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:

uv add "cognoxium[arrow]"

or:

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 Trust boundaries and policies.

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.