Troubleshooting

Most checks here run in a terminal with the kcap command-line tool. Where the desktop app offers the same step, it is named too

I can’t sign in

In the web app

• Check the address. Your workspace is at https://<your-workspace>.kcap.ai, where <your-workspace> is the name chosen when it was created. A misspelt name lands on an Unknown tenant error or on nothing at all; ask whoever invited you for the exact address
• The browser signed you in with the wrong account. Sign-in reuses the Google, Microsoft or GitHub account the browser already holds, and if that is not the account the invitation went to, the workspace refuses you. Sign out of the web app, then sign in again in a private window, or switch the browser’s account first, using the invited account
• The invitation went to another address. Ask a workspace admin to check Administration → People

From the terminal or the desktop app

• Discovery does not list the workspace because it uses the GitHub App rather than single sign-on. In a terminal, kcap setup --github, or kcap setup --slug <your-workspace> with the name from the address
• No browser on this machine, for example over SSH. kcap login --device prints a code and a URL to approve on any other device
• Signed in to the wrong workspace. kcap whoami shows who you are signed in as and which server; kcap login --discover lists your workspaces to pick again. When the desktop app is signed out, Help and support offers Sign in
• The device sign-in timed out. Run it again

My session doesn’t appear

• In a terminal, run kcap status. It shows whether the server is reachable, who you are signed in as, and for each coding agent whether its hooks are installed and when the last event arrived. An agent that is detected but not wired is listed with the command that wires it
• Restart the coding agent if it was already running when setup ran; hooks are loaded when the agent starts
• Codex stores nothing until you trust the hooks; see Codex sessions aren’t captured
• Check the folder is not excluded. kcap ignore --list shows the excluded paths and kcap allow --list the allow list, if you set one. A folder that is excluded, or outside the allow list, is never stored; exclusion wins
• Outside a git repository with a remote, the session is stored but belongs to no repository, so a repository or project scope hides it. In the web app, set Scope to All Repositories and open Sessions
• The session was stored under a different account from the one you are signed in to the web app with, and sessions are private by default, so the web app cannot show it. Compare kcap whoami in a terminal with the account in the web app’s avatar menu. Either sign in to the web app as that person, or run kcap login and sign in as the account you use in the browser, so future sessions are stored under it

The local server won’t start

In a terminal, kcap local status names which part failed and what to do; kcap local logs prints the output of the server, Postgres and KurrentDB; kcap local start finishes or undoes an interrupted setup, upgrade or purge. The desktop app shows a recovery screen for the same situation with a restart; the logs are read from a terminal

The desktop app can’t reach the daemon

The daemon is the background service that runs hosted agents and keeps the app connected. In a terminal:

kcap daemon service status
kcap daemon service ensure      # installs and starts the service if it is missing
kcap daemon doctor --clean      # removes the records of daemons that no longer run

If the app says kcap is not available, the command-line tool is not on your path: open Help and support → Set up kcap… in the app and accept the offer to link it, or run kcap daemon shim ensure in a terminal

Codex sessions aren’t captured

Codex runs only hooks you have trusted, and kcap’s hooks do nothing until then

• Codex CLI. Start codex in a terminal. The first start after kcap installed the hooks asks whether to trust them; accept, and all of them are trusted. If no prompt appears, type /hooks inside Codex, find the kcap entries and trust each one
• Codex desktop app. It never shows that prompt. Open the Codex app’s Settings → Hooks and trust the kcap entries there. If no kcap entries are listed, run kcap plugin install --codex in a terminal first, then look again
• A hooks file Codex refuses, for example one with a byte-order mark, is reported by kcap status

Hooks stopped working after an update

In a terminal, run kcap refresh. It brings every integration kcap installed earlier up to the installed version: hooks, skills, MCP registrations and the daemon service. If it reports a failed step, run kcap setup again. The desktop app runs the same refresh each time it updates itself. Installs scoped to one repository are never refreshed: run kcap plugin install --project in that repository again

My agent doesn’t have the kcap tools

The kcap MCP servers are registered per coding agent and loaded when the agent starts. In a terminal, kcap status shows whether the agent is wired; kcap plugin install --codex, or the flag for that agent (the plugin command reference lists them), registers the servers; then restart the coding agent. A setup an agent ran inside its own session takes effect in its next session. Grok Build has no MCP registration by design

A vendor is missing from the launch dialog

The daemon offers a coding agent only when it can find and run that agent’s command on its own machine. On that machine:

1. Install the vendor’s CLI and sign in to it
2. Let the daemon see it. The service captured your PATH when it was installed, so after installing a new CLI run kcap daemon service install --replace in a terminal; it reinstalls the service with the current PATH and restarts the daemon. KCAP_<VENDOR>_PATH, for example KCAP_CODEX_PATH, points the daemon at a binary that is not on the path

A reviewer vendor can also be withheld when the kcap on that machine is too old to carry a launcher policy for it. Run kcap update on that machine; the daemon restarts itself on the new version

Import found fewer sessions than expected

Each import starts with a list of working directories that the recorded sessions name but that no longer exist on disk: folders you renamed, moved or deleted since. kcap cannot tell which repository those sessions belong to, so an import limited to a repository or an organisation skips them. To recover them, tell kcap where each folder is now and run the import again:

kcap remap ~/dev/old-folder ~/dev/new-folder
kcap import --org <your-org>

kcap remap --list shows the mappings you have made. Sessions in a worktree under the project folder are placed automatically. Gemini recordings with no initial context cannot be placed by repository and are skipped under an allow list. Cursor imports only Agent-mode sessions

”Catching up” or “Rebuilding” won’t clear

The server is still processing. Catching up means recent events are being applied and usually clears within minutes. Rebuilding means the server is reconstructing one of its indexes after an update, which can take an hour or more on a workspace with many sessions. Until it clears, lists and counts are incomplete, but nothing is lost: a session you cannot find yet will appear, and changes you make meanwhile are saved and show when it finishes

A session is missing records

A record too large to process is replaced by a numbered capture-loss marker and the session shows a warning; file totals or the plan may be incomplete. You can repair it from the machine that stored it when three things hold: the session has ended, it came from Claude Code or Codex, and you are its owner. In a terminal:

kcap import --session <id> --repair-capture --dry-run    # reports what it would recover
kcap import --session <id> --repair-capture

The session id is the last part of the session’s URL in the web app. Exit code 0 means nothing is missing any more; 2 means some gaps remain; 1 means it refused, because the transcript is gone or has changed, or because the session is still running on the server

I’m storing as the wrong identity

Start in a terminal:

kcap whoami
kcap status

kcap whoami prints the account, the profile and the server this terminal stores under. Read it against what you expected:

• kcap status warns that KCAP_CLIENT_ID or KCAP_CLIENT_SECRET is set. Machine credentials in your shell environment turn every process into that machine and override your own sign-in. Find where your shell sets them (~/.zshrc, ~/.bashrc, a direnv file) and remove them, then open a new terminal
• The server or profile is the wrong workspace. Another profile is active. kcap use <profile> --global switches it everywhere; kcap use <profile> run inside a repository binds that repository to it
• The account is a real one, but not the one you use in the web app. Run kcap login and sign in as the account you use in the browser

A flow is stuck or lost its run ID

Ask the agent to check the flow’s status; without an id it reads the newest open run this session started, or, on agents that do not identify their session to kcap, the newest from this repository on this machine. A round can outlast a tool call; the flow keeps running. Failed means the reviewer did not finish: read its session under Flows → Participants

The daemon keeps disconnecting

Start by reading the daemon’s own log, in a terminal on the machine that runs it:

kcap daemon logs
kcap daemon status

Then match what you see:

• The sign-in expired. kcap login on that machine, then kcap daemon restart
• A command it needs is not found, or the environment changed since the service was installed. The service captured your PATH at install time. kcap daemon service install --replace reinstalls it with the current PATH and restarts it
• A launch approval is waiting with nobody to answer it. On a machine nobody watches, set a standing decision: kcap daemon consent allow or kcap daemon consent deny
• The server wants a newer kcap. kcap update on that machine; the daemon restarts itself on the new version
• Leftover records from daemons that no longer run. kcap daemon doctor lists them; kcap daemon doctor --clean removes the record of any daemon whose process is gone, and never touches a running one

A machine credential is rejected

A machine signs in with two environment variables, KCAP_CLIENT_ID and KCAP_CLIENT_SECRET. Both must be set; a runner with only one fails with a message naming the missing one. A wrong or revoked value is rejected by the server: an admin revokes the machine under Administration → Integrations → Machines and creates a fresh one. The runner also needs network access to two addresses: signin.kcap.ai, which issues the token, and your workspace at https://<your-workspace>.kcap.ai