Troubleshooting
Fix common errors and unexpected results.
Invalid capability
capability() throws immediately when the definition is wrong.
capability() requires a non-empty name.Give the capability a name such as"payments.refund".capability() requires an authorize function.Addauthorize. There is no default.capability() requires input to be a Standard Schema (missing "~standard" property).Pass a Standard Schema V1 schema. Zod, Valibot, and ArkType work as they are.capability() input schema must implement Standard Schema version 1.The schema’s~standard.versionmust be1.capability() input schema must provide a "~standard.validate" function.Add avalidatefunction to the schema’s~standardobject.
Request errors
This happens when the request cannot start: an empty principalId or idempotencyKey, input that fails validation (InvalidInputError), input Kaji cannot fingerprint (UnfingerprintableValueError, for example a Map, a circular reference, or an invalid date), or a store failure on claim() (KajiConfigurationError). Fix the request or the store and try again.
createKaji() also throws a KajiConfigurationError when timeoutMs is not greater than 0 and at most 2,147,483,647.
Unexpected status
denied:authorizereturned anything other thantrue, or threw. A function that forgets toreturnis denied. Check your permission rules. The original error, if any, is inerror.rejected: approval was required and not given, orapprovalthrew. Anasyncapprovalfunction always requires approval, so make it synchronous. Check thatcreateKaji()has anapprovefunction, that it returns{ approved: true }when you want the action to run, and that it does not throw.failed: either the idempotency key was reused with different input, orexecutethrewknownFailure(). For the first, use the original input to retry, or a new key for a new request.unknown: see Unexpected unknown.
Retries
That is intended. The same capability, principalId, idempotencyKey, and input return the saved result. Use a new idempotencyKey for a new request. This includes a saved unknown: check with the provider, then use a new key only once you know a new request is safe.
Unexpected unknown
Kaji cannot tell whether the side effect happened before the error. Throw knownFailure(cause) only when you know it did not. See Outcomes.
You also get unknown if the store fails to save the result. Check the store before retrying.
Timeouts
The timeout only aborts context.signal. Pass the signal to the API you call, or check it yourself. See Cancellation.
Lost records
memoryStore() only keeps records in memory for one process. Use a store backed by a database in production. See Stores.