Errors
Reference for every error class in the Kumiko framework.
Every error response carries a docsUrl of the form
https://docs.kumiko.rocks/errors/<slug>, which redirects to the page below.
The slug is the reason in details.reason when the framework documents it,
otherwise the error code. Self-hosted docs set KUMIKO_DOCS_URL.
Framework
Section titled “Framework”| Error | Type | When it fires |
|---|---|---|
delete_restricted | ConflictError | Cascade-delete guard refused because dependent rows exist |
feature_disabled | FeatureDisabledError | Handler’s owning feature is globally disabled |
field_access_denied | AccessDeniedError | Dispatcher’s field-level write check blocked a field |
file_rejected | UnprocessableError | createFileRefFromBytes refused the file (size, type, content or attach target) |
identity_switch_denied | AccessDeniedError | ctx.dispatch.queryAs/ctx.dispatch.writeAs switched to another non-system identity without r.systemScope() or an escape hatch |
instruction_field_write_requires_high_risk | AccessDeniedError | A handler writes a readAsInstruction field but its agent.risk is below "high" |
invalid_transition | UnprocessableError | GuardTransition rejected a state-machine transition |
irreversible_operation_requires_high_risk | AccessDeniedError | A handler hard-deletes or forgets data but its agent.risk is below "high" |
irreversible_operation_without_entry_handler | AccessDeniedError | A job or consumer without a directly dispatched entry handler performs an irreversible operation but declared no irreversibleWithoutEntryHandler exception |
member_resolution_denied | AccessDeniedError | ctx.dispatch.queryAsMember named a user who is no active member of the tenant |
member_resolution_read_only | AccessDeniedError | A query run through ctx.dispatch.queryAsMember tried to write |
notify_foreign_tenant_broadcast | AccessDeniedError | ctx.notify named another tenant in to: { tenant } |
public_intake_required | AccessDeniedError | An anonymous write touched a personal-data field without access.personalData: "public-intake" |
stale_state | ConflictError | Atomic UPDATE lost the race (another writer moved the row) |
subject_erased | ConflictError | A write touched personal data of a subject whose key was erased |
system_identity_switch_denied | AccessDeniedError | ctx.dispatch.queryAs/ctx.dispatch.writeAs switched to the system identity without r.systemScope() or an escape hatch |
tenant_override_requires_system_admin | AccessDeniedError | A payload carried tenantIdOverride but the caller is no SystemAdmin |
unsafe_all_tenants_denied | AccessDeniedError | ctx.dispatch.queryProjection with unsafeAllTenants ran without r.systemScope() or an escape hatch |
Error codes
Section titled “Error codes”Errors without a more specific reason link to the page of their code.
| Error | Type | When it fires |
|---|---|---|
access_denied | AccessDeniedError (403) | The caller may not run the handler or touch the record |
cap_exceeded | CapExceededError (429) | A usage cap of the plan reached its hard threshold |
conflict | ConflictError (409) | A write clashes with the current state of the data |
idempotent_replay | IdempotentReplayError (409) | A write repeated an idempotencyKey that was already stored |
internal_error | InternalError (500) | An unexpected throw on the server; details only in the log |
member_read_timeout | MemberReadTimeoutError (504) | A ctx.dispatch.queryAsMember read hit its statement timeout |
not_found | NotFoundError (404) | The record does not exist or is not visible to the caller |
platform_budget_exceeded | PlatformBudgetExceededError (429, enterprise) | The AI token budget on the platform key is used up |
precondition_failed | PreconditionFailedError (409) | A field no longer holds the value the write expected |
puppeteer_unavailable | PuppeteerUnavailableError (503) | The PDF service did not answer, no PDF was created |
rate_limit_unavailable | RateLimitUnavailableError (503) | The rate-limit backend failed, the request was refused |
rate_limited | RateLimitError (429) | The caller exceeded a rate limit |
record_locked | RecordLockedError (409) | The record’s lockedWhen condition holds, so it cannot change |
release_storage_unavailable | ReleaseStorageUnavailableError (503, enterprise) | The release storage backend did not answer, the caller may retry |
unauthenticated | UnauthenticatedError (401) | A handler that needs a signed-in user was called without one |
unconfigured | UnconfiguredError (422) | A required tenant setting has no value yet |
unique_violation | UniqueViolationError (409) | A write would break a unique index of the entity |
unprocessable | UnprocessableError (422) | A business rule rejected the request; reason in details.reason |
validation_error | ValidationError (400) | The payload does not match the handler’s schema |
version_conflict | VersionConflictError (409) | Another writer changed the same record first |
AI agent
Section titled “AI agent”Reasons the agent runtime surfaces, tool dispatch, the permission gate and the risk gate, rather than a handler’s own domain logic. See The Assistant.
| Error | Type | When it fires |
|---|---|---|
agent.high_risk_no_always | UnprocessableError | An always permission rule was requested for an agent: { risk: "high" } handler; use per-call approval instead |
agent.iteration_limit | UnprocessableError | The agent loop hit its maximum round count before producing a final answer |
agent.tool_not_allowed | UnprocessableError | The model requested a tool outside the run’s catalog, or a permission rule names a handler the caller cannot see |