Troubleshooting

Kisenon is in alpha. Here are the failure modes you are most likely to hit, and how to get past each.

Endpoint stuck in Pending

Symptom: an endpoint sits in Pending for more than a few seconds on creation. The console shows no error; the CLI shows the same state.

Likely cause: the compute pod cannot be scheduled. The most common reasons are cluster pressure (no node has the requested CPU or memory free) or a stale image-pull credential. Both are operator-side issues.

What to do:

1. Wait 60 seconds. Transient pressure usually clears once another endpoint suspends.
2. If it does not clear, delete the endpoint and recreate. The control plane will retry scheduling on a different node.
3. If recreation also lands in Pending, the cluster is unhappy. File a report at the GitHub tracker with the endpoint id and the wall-clock time.

FATAL: endpoint unavailable on first connect

Symptom: psql returns FATAL: endpoint unavailable on the very first connection to a freshly created endpoint, or after a long idle.

Likely cause: cold-start race. The endpoint state is Stopped, your packet woke it, but Postgres is still replaying WAL up to the branch HEAD when your client gives up.

What to do: retry the connection. Cold-start typically completes in 300–500 ms, but the very first wake of a freshly created project, or after a 24h+ idle, can take 10–30 seconds while the pageserver page cache warms. Most drivers tolerate this if you allow at least one retry; raw psql does not retry by default.

# psql with one explicit retry
for i in 1 2; do psql "$URI" -c '\q' && break; sleep 5; done

If the endpoint is still unavailable after 30 seconds, the pod itself may have failed — check the state in the console and consult the Pending guidance above.

Branch appears empty after fork

Symptom: you create a branch from main at HEAD, attach an endpoint, and \dt returns an empty list — but the parent has tables.

Likely cause: known issue under investigation. Branch materialisation can lag the create call under specific WAL-flush timings. The branch row is ready before the pageserver has the full parent state available to it.

What to do:

1. Disconnect.
2. Wait 10 seconds.
3. Reconnect. The branch should now reflect the parent's HEAD.

If the branch is still empty after 60 seconds, file a report with the project id, branch id, parent branch id, and the LSN you forked at (if you specified one).

keon connection-string returns branch_not_found

Symptom:

$ keon connection-string my-feature --project prj_abc...
Error: branch_not_found

…but the branch exists in the console.

Likely cause: you passed the branch name where the CLI expected the branch id. The CLI accepts both, but only on the --branch flag, not the positional argument in older v0.1.x builds.

What to do: pass the branch name via --branch:

keon connection-string --project prj_abc... --branch my-feature

Or upgrade the CLI to the latest release, which accepts the name as a positional argument:

curl -fsSL https://kisenon.com/install.sh | bash

Sign-in returns access_denied

Symptom: Google or GitHub OAuth completes, but the console redirects to an error page citing access_denied.

Likely cause: during alpha, sign-in is gated by an email allowlist. If your address has not been onboarded, the sign-in callback rejects it on principle.

What to do: apply at Alpha access. Once your address is added to the allowlist, sign-in completes normally on the next attempt.

Console session expires mid-session

Symptom: the console works for a while, then suddenly returns 401s on every API call until you sign out and back in.

Likely cause: the cp-signed JWT and its refresh window both expired. The console refreshes the JWT in the background while you are active; if you have left a tab open for several hours without clicking anything, the refresh window can lapse.

What to do: sign out and back in. Future console builds will prompt rather than silently 401; the underlying JWT refresh is the right long-term fix.

Where to file bugs

For anything not covered here:

• Product bugs and feature requests: the GitHub tracker.
• Security vulnerabilities: Security — never on the public tracker.

Concrete repro steps, the affected ids (project, branch, endpoint), and a wall-clock timestamp shorten the round-trip dramatically.