Troubleshooting
Find your symptom, read the cause, apply the fix. Each entry has its own link, so other pages can point straight to it.
401 Unauthorized
You see {"jsonrpc":"2.0","error":{"code":-32001,"message":"Unauthorized"}}, or your client says the server "rejected the configured Authorization header (HTTP 401)".
Cause: /mcp needs the Kernl token. The header is missing, or the token is wrong or stale (for example you pinned a new KERNEL_AUTH_TOKEN).
Fix: print the current token (see First run) and update your client. In Claude Code, remove the server and add it again. See Claude Code. Check the exact header text: Authorization: Bearer <token>.
Unexpected token '<'
Your client says Unexpected token '<', Unrecognized token '<' or "<!DOCTYPE" is not valid JSON.
Cause: the client expected JSON and got HTML. The < is the start of <!DOCTYPE html>. Usually the token is missing or wrong: the client tried to sign in some other way, and the dashboard answered with its web page. A wrong URL is a likely cause of the same result.
Fix: treat it as a 401. Check the token, and check that the URL ends in /mcp and uses port 3086.
Session not found
You get 404 with {"jsonrpc":"2.0","error":{"code":-32000,"message":"Session not found"}}.
Cause: the mcp-session-id you sent is unknown. Kernl may have removed it after 10 minutes of silence (from the source), or Kernl may have restarted.
Fix: send initialize again and use the new session id. See Other clients. Normal apps do this on their own. If one does not, restart it.
Missing mcp-session-id
You get 400 with Missing mcp-session-id header.
Cause: you sent a request that needs a session, such as GET /mcp, without the mcp-session-id header. A tools/list without the header gives Bad Request: Server not initialized.
Fix: call initialize first and send the returned mcp-session-id on every later request. See MCP basics.
Port 3086 is in use
Kernl does not start, or the dashboard shows another program.
Cause: something else already listens on port 3086.
Fix: find and stop that program. On Windows you can instead move Kernl (from the packaging, not run by us): set DASHBOARD_PORT=3088 in %APPDATA%\Kernl\.env and restart. Remember to use the new port in the MCP URL.
No token yet
kernl token prints kernl: no token yet — it is generated on the first boot. and exits with an error.
Cause: Kernl has never started, so it has not made a token.
Fix: start Kernl once, wait a few seconds, and run the command again. On Linux:
systemctl --user start kernl
kernl token
The systemctl line is the one kernl token itself suggests; we did not run it, because our test containers have no systemd. This is for the deb and rpm packages. With the tarball there is no service: run kernl itself, and if ~/.local/bin is not on your PATH, call ~/.local/bin/kernl token.
On macOS open the app once. On Windows run start.bat once. With the tarball, run kernl.
Reachable from my network
Other computers on your network can open your dashboard.
Cause: by default the Linux packages listen on all addresses (0.0.0.0). Nobody can log in without the token, but the page is visible.
Fix: restrict Kernl to this computer. Add this line to ~/.config/kernl/.env, then restart Kernl:
KERNEL_DASHBOARD_BIND=127.0.0.1
This setting comes from Kernl's code; we have not tested it. If you do this, a LAN address no longer works in your MCP client either.
"Unidentified developer" or SmartScreen warning
macOS says Kernl cannot be opened, or Windows says it protected your PC.
Cause: the macOS and Windows builds are not signed yet.
Fix on macOS: click Done, open System Settings, Privacy & Security, and click Open Anyway. Or run:
xattr -dr com.apple.quarantine /Applications/Kernl.app
Fix on Windows: click More info, then Run anyway.
macOS and Windows steps come from Kernl's packaging; the Kernl team has not run them on those systems yet.
Claude Desktop typically shows "Server disconnected"
Cause: a likely one is Node 18 or older. The bridge needs Node 20.
Fix: run node --version and upgrade if needed. See Claude Desktop.
Neo4j unavailable in the log
The log says Neo4j unavailable — graph features will be disabled.
Cause: a package install has no Neo4j database.
Fix: none needed. It is harmless. Only the graph features are off.