Reference

Troubleshooting

Every error kalp shows is meant to tell you the fix. This page collects them all in one place, with a little more detail.

"claude code cli not found"

claude code cli not found — install: npm i -g @anthropic-ai/claude-code

Where you see it: in the editor panel when it opens, in the terminal when the bridge starts, or when you click apply.

What it means: the claude command is not on your PATH, so kalp has no way to edit files.

Fix:

npm install -g @anthropic-ai/claude-code
claude        # open it once
/login        # and authenticate

If you installed Claude Code through a Node version manager (nvm, fnm), make sure the terminal where you run kalp uses the same Node version — otherwise the binary exists but isn't on that shell's PATH. No restart is needed after fixing: kalp re-checks automatically.

"claude code is not logged in"

claude code is not logged in — run `claude` in a terminal, then /login

Where you see it: same places as above.

What it means: the CLI is installed, but kalp found no working credentials — no login, no ANTHROPIC_API_KEY, no other credential source. You may also see this when a login has expired: the pre-flight check passes but the run itself fails, and kalp reads Claude's own "please log in" output and shows this message.

Fix: open a terminal, run claude, type /login and follow the prompts. Or set the ANTHROPIC_API_KEY environment variable before starting kalp. Your pending edits are kept — once logged in, just click apply again.

"could not reach kalp server"

could not reach kalp server — is it running? (kalp & vite)

Where you see it: in the panel when you click apply.

What it means: the browser couldn't talk to the bridge server. Either it was never started, it crashed, or it started after the page loaded (the component searches for the server once, when the page loads).

Fix: make sure your dev script runs both processes — "dev": "kalp & vite" — then reload the page so the component can discover the server again.

"claude failed: …"

claude failed: <the last line of claude's output>

Where you see it: in the panel after an apply that went wrong for a reason other than credentials.

What it means: Claude Code started but exited with an error. The message shows the last line of its output, which usually names the problem. The full output is in the terminal where kalp is running — that's the first place to look.

Fix: depends on the message. Your edits stay in the panel, so you can apply again once the cause is resolved.

Nothing shows up in Next.js

What it looks like: the app builds, but there's no paintbrush button — or the build fails with an error about browser APIs or client components.

What it means: <Kalp /> uses browser-only APIs, so in the App Router it must be rendered from a Client Component.

Fix: wrap it in a file with "use client" at the top and render that wrapper from your layout — the exact snippet is in Getting Started.

Ports 3001–3010 are all busy

What it looks like: kalp exits immediately with [kalp] no available port found between 3001 and 3010.

What it means: ten other processes already hold every port in kalp's range.

Fix: free one of those ports. Note that the component probes only 3001–3010, so a custom --port outside that range won't be discovered — prefer keeping kalp inside the range.

Still stuck?

Open an issue on GitHub with the terminal output from kalp and the message shown in the panel — those two together almost always identify the problem.