Reference
Troubleshooting
Resolve common setup, authentication, policy, and approval problems.
The local server will not respond
Confirm npm run dev is running, dependencies installed, and the base URL matches its printed port. Use Node 22.13.0 or newer. If a server for this checkout is already running, use that URL.
For 500, inspect the terminal for database or runtime errors. Do not delete local database state as the first troubleshooting step.
401: invalid API key
Use the full raw key from server bootstrap or rotation. A display prefix, placeholder, or dashboard demo key is invalid.
Check that it belongs to this instance and has not been revoked. Bootstrap does not reveal the key twice; rotate through the owner API if lost and update every client.
Authentication required or project missing
authentication_required on an owner endpoint needs owner identity, not the agent key. Use an authenticated hosted session. The curl management examples are unauthenticated only on localhost.
project_not_initialized means bootstrap is required for that owner. Hosted and local instances have separate data and keys.
An HTML login page can mean hosting access blocked the request before Kernall received it. Confirm the external-client access path with the instance administrator.
The verdict is unexpected
- Denied: inspect the allowlist. Non-empty allowlists deny missing destinations and uncovered hosts.
- Needs review: submit, payment, and delete pause by default, even without sensitive data.
- Review was skipped: verify the action name and flagged categories. Detection is coarse and only the first match counts.
- Policy edit did nothing: read server policy back and test with a new idempotency key. Replays return the old decision.
A review stays pending or cannot be found
Use confirmation_id, not check_id, with a key for the same project. Wrong or cross-project reviews return 404.
Resolve via the owner API. Demo buttons and client timeouts do not update durable reviews. A 409 means an opposite result is already recorded; create a new proposal if a new decision is needed.
The dashboard disagrees with the API
400, 429, or repeated records
For 400, inspect the error and check types and lengths. Policy replacement requires all three arrays, including empty ones.
For 429, wait the Retry-After interval. Use the status endpoint to poll a review instead of making new checks.
Duplicate checks often mean retries used new or missing idempotency keys. Replays are intentional; change the key only for a new logical action.
Python cannot import kernall
Run from the repository root with PYTHONPATH="$PWD/sdk/python" as in the Python guide. Similar registry packages are not verified substitutes.
If import works but requests fail, verify the running API and real project key. A review timeout leaves the action blocked.
Get help
Send a support question with the route, HTTP status, error code, runtime version, local/hosted context, and reproduction steps. Remove secrets and sensitive payloads.