Troubleshooting
Find the next safe step: each symptom below gives you one action and the
details support needs if that action does not resolve it. ks doctor is the usual
first move (/doctor in the app): it reports connectivity, your
token and your client version together, which separates a network problem
from a sign-in problem.
Everything here runs on your own machine with your own account and needs no special privileges. Nothing on this page asks you to change our infrastructure.
symptom
You cannot sign in from the client
What it means
The client signs in through a browser device flow and stores a token locally. A failure here is usually the token or the connection, not your account.
What to do
Run ks doctor, which checks connectivity, your token and your client version. If it reports a token problem, run ks logout and then ks login again.
If you contact support, include
The email address on the account and the approximate time of the failed attempt, in UTC.
symptom
A command reports that the session is not found or not yours
What it means
Sessions belong to the account that created them. A session id from another account is refused rather than shown, so a wrong-account sign-in looks the same as a missing session.
What to do
Run ks doctor: its first line names the account you are signed in as. If it is the wrong one, sign in as the owning account with ks logout followed by ks login.
If you contact support, include
The session id and the account you expected to own it.
symptom
A session or an agent is paused and does nothing
What it means
A paused session is saved, not lost: its filesystem, memory and running work are already written to a checkpoint, and the client shows its state as parked. Opening an agent never wakes its session by itself.
What to do
In the app, open the agent and press r when it says the session is paused, or type /resume. From a terminal, ks agent resume ; for a plain session, ks wake . It resumes from the checkpoint rather than starting over.
If you contact support, include
The session id, if it does not wake.
symptom
Work stopped and your credit balance is at zero
What it means
When an account's credit runs out, its running sessions are saved and paused rather than killed, and the work is not discarded. Adding credit does not resume them by itself. Paid credits do not expire; free credits expire 90 days after they are issued.
What to do
Add credit in the console at ctl.keepstate.ai, then resume: /resume in the agent's window, ks agent resume from a terminal, or ks wake for a plain session. Unused paid credits can be refunded within 14 days of purchase through Polar, the merchant of record.
If you contact support, include
The session id and the time work stopped.
symptom
Model calls are refused because the session's budget is spent
What it means
A session's token budget bounds the model calls its machine makes, and the gateway refuses calls past it. This is the session's budget, not your account's credit. A plain session is saved and paused at its budget; for an agent session, pausing at the budget has not been tested on its own.
What to do
Read where the session stands with /usage (ks session usage ). A new session takes a larger budget with ks run --budget-tokens N.
If you contact support, include
The session id and the output of ks session usage.
symptom
A command is missing or behaves differently from the reference
What it means
The documented commands describe the current released client. An older installed client can be missing a verb entirely.
What to do
Check with ks version, then update with ks update, which verifies the download checksum before installing.
If you contact support, include
The output of ks version and the exact command you ran.
symptom
A save did not complete
What it means
A save that fails is recorded as a failure with its reason. It does not silently disappear, and a failed save does not damage the session.
What to do
Save again. If it fails a second time, stop and contact support rather than retrying in a loop.
If you contact support, include
The session id, the time of both attempts in UTC, and the error the command printed.
symptom
Commands hang or time out
What it means
The client talks to the control plane over the network. A hang is usually connectivity or a stale token rather than the session itself.
What to do
Run ks doctor. It reports connectivity, token and version together, which distinguishes a network problem from a sign-in problem.
If you contact support, include
The ks doctor output and the command that hung.
symptom
An agent command says the session is a plain session with no agents
What it means
A plain session (started by ks run without --agent) has no agents, so there is nothing named in it to open, tell or approve. The agent commands work on agent sessions.
What to do
Start an agent session: ks, then n, or ks run --agent --agent-name . A plain session's own terminal is ks attach , outside the app.
If you contact support, include
The session id and the command you ran.
symptom
A new agent reads starting, supervised and waiting for its first instruction, and not ready
What it means
That is the expected state of a new agent: its runner starts on its first instruction, so it reads ready only after that. Nothing is wrong and no model call has been made.
What to do
Give it an instruction: type it in the app, or from a terminal ks agent tell .
If you contact support, include
The session id, if it stays in that state after an instruction.
symptom
The agent's first model call is refused: the session is not bound to a key for that provider
What it means
A session's calls go out on the key bound to it and on no other. This session has no key bound for the provider its agent calls, so the gateway refused the call and nothing was billed.
What to do
Bind a key: /session key set --key in the agent's window, or ks session key set (/keys shows your keys; ks key add, in a terminal, stores one). The refused instruction failed and holds the queue, so continue it with /agent queue resume --finding "key bound" (ks agent queue resume ), then send the instruction again.
If you contact support, include
The session id and the time of the refused call.
symptom
An agent reads waiting_approval and does not move
What it means
It asked permission to run something and waits for your decision. It never decides for itself.
What to do
Open it in the app and answer the prompt (y allows once, n denies, d shows the details); /approvals lists every request waiting. From a terminal, ks approval list --session and then ks agent approve .
If you contact support, include
The request id, if a decision is refused.
symptom
An agent reads failed or recovery_required, or its queue is held
What it means
Its runner stopped, or an instruction failed, and what it was doing is not known. The instructions behind it are held, because they may have been written expecting its result. Nothing starts until a person decides.
What to do
Read the choices with /queue in the agent's window, then continue the held instructions with /agent queue resume --finding "..." or keep them held with /agent queue hold --finding "...". From a terminal: ks agent queue show , then ks agent queue resume or ks agent queue hold .
If you contact support, include
The session id, the agent's name and the task id the queue names.
symptom
A command is refused with ks_client_too_old
What it means
The operation is newer than the protocol your client speaks, so the service refuses it by name instead of answering in a shape the client cannot read.
What to do
Update the client with ks update, which verifies the download before installing, and run the command again.
If you contact support, include
The output of ks version and the exact command you ran.
symptom
None of the above resolves it
What it means
Support can read the session's own record. What support needs is enough to find it.
What to do
Open a support request at keepstate.ai/support with the details below. We reply within two business days.
If you contact support, include
The session id, the approximate time in UTC, the command you ran, and your client version from ks version. Never include a provider key or any other credential.