Troubleshooting
Find your symptom below, or start with kndl doctor on the machine that misbehaves.
Run kndl doctor
Section titled “Run kndl doctor”kndl doctorIt checks the install, the settings, the services and the Hub’s health, and prints ok, !! (a warning) or XX (a failure) for each, with what to do. To repair what it can, after asking:
kndl doctor --fixWhere to look
Section titled “Where to look”| Where | What it tells you |
|---|---|
kndl status | Whether the services run, the Hub answers and the Runner is connected. |
kndl logs hub, kndl logs runner | Why a service won’t start, refused connections, sign-in failures, what happened to Sandboxes. Add -f to follow. |
| A Session’s transcript | A line each time its state changes, with why: The Session is Asleep: …. |
| Show log on a Session’s Starting… banner | The output of its Build, Bootstrap script and Start script. |
| A Session’s Terminal tab | Claude Code’s own screen. |
https://<your Hub>/health | {"status":"ok"} when the Hub is up. |
Running kndl from a checkout? The logs are in the terminals running bun run hub and bun run runner, and the Hub’s settings in packages/hub/.env.local. See Develop kndl.
By symptom
Section titled “By symptom”| What you see | Where |
|---|---|
kndl: command not found right after installing | Install |
kndl install: Could not clone … | Install |
kndl is not installed in … | Install |
onboard can't ask, so it needs --role hub|runner|both. | Install |
| Onboard can’t create the GitHub App | Install |
| A service won’t stay up | Install |
| On Linux, the services stop when you log out | Install |
KVM access: … can't open /dev/kvm. | Install |
sudo: a terminal is required to read the password | Install |
bun: command not found while building | Install |
… is readable by others (mode 644); … | Install |
kndl update stays where it is | Install |
kndl uninstall refuses the home | Install |
Failed to start server. Is port 7777 in use? | Hub |
The Hub's web UI isn't built. | Hub |
Dev login (KNDL_DEV_LOGIN) is refused: … | Hub |
The Hub refuses HUB_SECRETS_KEY | Hub |
| The secrets key is lost | Hub |
… a Hub is running on …/hub.db. Stop it first. | Hub |
HubConfigError: … about GitHub settings | Hub |
| A Session can’t start because of an MCP server Installation | Hub |
| An MCP server’s tools fail in a running Session | Hub |
| Couldn’t connect an OAuth Installation | Hub |
| Enter a client for an OAuth Installation | Hub |
| A Global Installation can’t be changed | Hub |
Only the web UI at … may make this request | Signing in |
| Sign-in doesn’t stick | Signing in |
the sign-in expired or came from elsewhere | Signing in |
This Hub is invite-only. | Signing in |
GitHub refused the sign-in: … | Signing in |
| No Sign in with GitHub button | Signing in |
Dev login only answers on loopback | Signing in |
kndl login: the browser can’t connect to 127.0.0.1 | Signing in |
That code isn't valid | Signing in |
… doesn't accept this machine's CLI token | Signing in |
Hub connection: could not connect to … | Runners |
| A Runner on another machine never shows up | Runners |
That pairing code can't be used | Runners |
Runner: not connected to the Hub after 30 seconds | Runners |
The Hub doesn't accept this Runner's token | Runners |
Runner … has … that aren't Archived. | Runners |
this Runner needs an update, or behind the Hub | Runners |
| refuses: not on main | Runners |
| update failed | Runners |
The Hub turned this Runner away: … | Runners |
| A Session is Frozen | Runners |
Unknown Sandbox for Session … | Runners |
The hub-link mod isn't built | Runners |
Expected string at ["RUNNER_TOKEN"], from a checkout | Develop kndl |
Claude Code could not start on … | Sessions |
Claude Code exited with code … | Sessions |
| A woken Session’s conversation starts over | Sessions |
… Sessions can't start: … need values | Sessions |
The Sandbox failed: … | Sessions |
| Test build failed | Sessions |
You don't have access to … on GitHub | Sessions |
| A Sensitive variable can’t be saved | Sessions |
| New Session asks for your Claude credential, or a Session sleeps for want of one | Sessions |
Only …, who started this Session, can drive it | Sessions |
| A Claude credential can’t be saved | Sessions |
There is no such Session. | Sessions |
| A Session doesn’t go to sleep | Sessions |
| Restart or Sleep now is refused | Sessions |
| Environment changed stays | Sessions |
git clone exited with 128 | GitHub and git |
The GitHub App is not installed on …, or can't see it | GitHub and git |
| The GitHub App is missing permissions | GitHub and git |
git push or gh fails in a Session | GitHub and git |
| Claude pushed to the default branch | GitHub and git |
Still stuck
Section titled “Still stuck”Search the issues, or open one with:
- what you ran,
- the exact message you saw,
- the relevant lines of
kndl logs hubandkndl logs runner, - the output of
kndl status.
Remove tokens and keys first. kndl’s own tokens start with ch, a letter and _, such as chr_… or chc_….
kndl is an independent project. It is not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic, PBC. About kndl