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 42424–42443 are all busy

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

What it means: twenty other processes already hold every port in kalp's range — usually twenty other kalp servers. (Very rarely, a short-lived outgoing connection can briefly hold one of these ports; kalp's scan simply skips past it.)

Fix: stop kalp servers you no longer need, or pin one explicitly: kalp --port 45000 together with <Kalp port={45000} /> — an explicit port binds exactly and skips discovery on both sides. Note that --port now fails cleanly if the port is taken instead of silently moving.

"multiple kalp servers found"

What it looks like: a small dark popover above the paintbrush button listing two or more project names, and an amber ! on the button.

What it means: more than one project on your machine is running kalp, and a web page can't know which folder on disk it came from — so kalp asks instead of guessing (a wrong guess would send your edits to the other project's source code).

Fix: nothing is wrong — click the project this page belongs to. The choice is remembered in this browser and re-verified on every reload, so you won't be asked again until the situation actually changes.

"kalp server changed — re-discovering, try again"

What it looks like: an apply fails with this message even though a kalp server is clearly running.

What it means: between page load and your click, the port kalp was bound to got recycled — typically you restarted two kalp servers in a different order, so a different project's server now answers on that port. The server refused the request (nothing was edited anywhere) and the component is finding the right server again.

Fix: just click apply to code again. Your pending edits were kept. If several servers are running you may see the picker once more.

Still stuck?

Reach out via the kalp page on npm with the terminal output from kalp and the message shown in the panel — those two together almost always identify the problem.