Skip to content

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.

ErrorTypeWhen it fires
delete_restrictedConflictErrorCascade-delete guard refused because dependent rows exist
feature_disabledFeatureDisabledErrorHandler’s owning feature is globally disabled
field_access_deniedAccessDeniedErrorDispatcher’s field-level write check blocked a field
file_rejectedUnprocessableErrorcreateFileRefFromBytes refused the file (size, type, content or attach target)
identity_switch_deniedAccessDeniedErrorctx.dispatch.queryAs/ctx.dispatch.writeAs switched to another non-system identity without r.systemScope() or an escape hatch
instruction_field_write_requires_high_riskAccessDeniedErrorA handler writes a readAsInstruction field but its agent.risk is below "high"
invalid_transitionUnprocessableErrorGuardTransition rejected a state-machine transition
irreversible_operation_requires_high_riskAccessDeniedErrorA handler hard-deletes or forgets data but its agent.risk is below "high"
irreversible_operation_without_entry_handlerAccessDeniedErrorA job or consumer without a directly dispatched entry handler performs an irreversible operation but declared no irreversibleWithoutEntryHandler exception
member_resolution_deniedAccessDeniedErrorctx.dispatch.queryAsMember named a user who is no active member of the tenant
member_resolution_read_onlyAccessDeniedErrorA query run through ctx.dispatch.queryAsMember tried to write
notify_foreign_tenant_broadcastAccessDeniedErrorctx.notify named another tenant in to: { tenant }
public_intake_requiredAccessDeniedErrorAn anonymous write touched a personal-data field without access.personalData: "public-intake"
stale_stateConflictErrorAtomic UPDATE lost the race (another writer moved the row)
subject_erasedConflictErrorA write touched personal data of a subject whose key was erased
system_identity_switch_deniedAccessDeniedErrorctx.dispatch.queryAs/ctx.dispatch.writeAs switched to the system identity without r.systemScope() or an escape hatch
tenant_override_requires_system_adminAccessDeniedErrorA payload carried tenantIdOverride but the caller is no SystemAdmin
unsafe_all_tenants_deniedAccessDeniedErrorctx.dispatch.queryProjection with unsafeAllTenants ran without r.systemScope() or an escape hatch

Errors without a more specific reason link to the page of their code.

ErrorTypeWhen it fires
access_deniedAccessDeniedError (403)The caller may not run the handler or touch the record
cap_exceededCapExceededError (429)A usage cap of the plan reached its hard threshold
conflictConflictError (409)A write clashes with the current state of the data
idempotent_replayIdempotentReplayError (409)A write repeated an idempotencyKey that was already stored
internal_errorInternalError (500)An unexpected throw on the server; details only in the log
member_read_timeoutMemberReadTimeoutError (504)A ctx.dispatch.queryAsMember read hit its statement timeout
not_foundNotFoundError (404)The record does not exist or is not visible to the caller
platform_budget_exceededPlatformBudgetExceededError (429, enterprise)The AI token budget on the platform key is used up
precondition_failedPreconditionFailedError (409)A field no longer holds the value the write expected
puppeteer_unavailablePuppeteerUnavailableError (503)The PDF service did not answer, no PDF was created
rate_limit_unavailableRateLimitUnavailableError (503)The rate-limit backend failed, the request was refused
rate_limitedRateLimitError (429)The caller exceeded a rate limit
record_lockedRecordLockedError (409)The record’s lockedWhen condition holds, so it cannot change
release_storage_unavailableReleaseStorageUnavailableError (503, enterprise)The release storage backend did not answer, the caller may retry
unauthenticatedUnauthenticatedError (401)A handler that needs a signed-in user was called without one
unconfiguredUnconfiguredError (422)A required tenant setting has no value yet
unique_violationUniqueViolationError (409)A write would break a unique index of the entity
unprocessableUnprocessableError (422)A business rule rejected the request; reason in details.reason
validation_errorValidationError (400)The payload does not match the handler’s schema
version_conflictVersionConflictError (409)Another writer changed the same record first

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.

ErrorTypeWhen it fires
agent.high_risk_no_alwaysUnprocessableErrorAn always permission rule was requested for an agent: { risk: "high" } handler; use per-call approval instead
agent.iteration_limitUnprocessableErrorThe agent loop hit its maximum round count before producing a final answer
agent.tool_not_allowedUnprocessableErrorThe model requested a tool outside the run’s catalog, or a permission rule names a handler the caller cannot see