# Troubleshooting

> Each error, and what to do. Every page of kelve's docs is listed at https://kelve.ai/llms.txt.

What kelve says when something's wrong, and what to do. Start with `kelve status`. It says whether kelve is running, where, and on which version.

## kelve isn't found

Your shell can't find the `kelve` command. Open a new terminal. If it still isn't found, add the folder the installer named to your PATH. On macOS and Linux, that's `~/.local/bin`.

## The installer stops

| It says | What to do |
|---|---|
| "kelve has no build for … yet." | Your system isn't one kelve has a build for. [Install it from source](/docs/install/). |
| "The download doesn't match the release's checksum, so it wasn't installed. Try again." | Something changed the download on its way. Run the installer again. |
| "kelve is running, so it couldn't be replaced. Run `kelve stop`, then try again." | On Windows: run `kelve stop`, then the installer again. |

## Setting it up

| It says | What to do |
|---|---|
| "No agent kelve knows is installed here. …" | Give your agent kelve as an MCP server that runs `kelve mcp`, as [Connect your agent](/docs/connect/) says, then run `kelve setup` again. |
| "kelve couldn't connect … itself. Run this where you use it: …" | Run the line it gives, in the terminal where you use your agent. |
| "kelve has hooks for … ." | kelve has no hook for the agent you named. Check its name against the list. An agent without a hook checks for notes, and asks for lessons, as kelve's instructions ask. |

## kelve doesn't start or open

| It says | What to do |
|---|---|
| "kelve didn't start. What went wrong is at the end of its log, …" | Read the end of the log it names, `kelve.log` in kelve's data folder. |
| "… isn't valid: …" | A setting in the environment can't be used. Change it as it says. [Environment variables](/docs/environment/) has each one. |
| "kelve's data was made by a newer kelve than this one, so this one can't read it. Run `kelve update`, then start kelve again." | Run `kelve update`, then `kelve open`. |
| "kelve couldn't copy its data aside before updating it, to …" | Make room on the disk, then run `kelve open` again. |
| "kelve couldn't open a browser. Run `kelve serve` in a terminal instead: it shows a link there." | Run `kelve serve`, and open the link it shows. |
| "kelve didn't say whether it opened. Check it's running with `kelve status`." | Run `kelve status`. If it's running, open the address it gives. |
| "kelve isn't running. Start it with `kelve serve`." | Run `kelve open`, or `kelve serve` to run it in that terminal. |
| "kelve didn't answer in time. Check it's running with `kelve status`." | Run `kelve status`. If it isn't running, `kelve open` starts it. |
| "kelve can't open a pull request by its address yet. …" | Check the pull request's branch out, then run `kelve diff main`. |
| "kelve couldn't show a picker here. …" | Open it from a terminal instead, with `kelve open` and its path. |

A sign-in link works once, within a minute. For a new one, run `kelve open`.

## The secret

| It says | What to do |
|---|---|
| "There's no secret yet. Run `kelve open` once; starting kelve makes the secret this command uses." | Run `kelve open` once. |
| "… can be read by other people on this computer. Make it yours alone with `chmod 600 …`, then start kelve again." | Run the `chmod` it gives, then `kelve open`. |

## Your agent doesn't have kelve's tools

Start a new session with your agent after you connect it. Agents load their tools when a session starts. Check the line you added, on [Connect your agent](/docs/connect/).

## Nothing's being read

If your agent's list says "Waiting for you to ask Claude Code", nothing's taking the work waiting there. Your agent stopped, or is busy with something else. Use **Copy what to say**, then paste it to your agent. It says what's waiting, for what that tab has open.

## Updating

| It says | What to do |
|---|---|
| "kelve couldn't find its newest release. Check you're online, then try again." | Check you're online, then run `kelve update` again. |
| "kelve couldn't download its newest release. …" | The same. |
| "kelve …'s release has no build for this computer yet. Try again later." | A new release can take a while to have every build. Try again later. |
| "kelve couldn't put the new version in …" | Run `kelve update` as someone who can write to that folder, or [install kelve again](/docs/install/). |
| "kelve is updated to …, but the kelve running didn't stop. Run `kelve stop`, then `kelve open`." | Run `kelve stop`, then `kelve open`. |
| "KELVE_UPDATES isn't valid: …" | Set `KELVE_UPDATES` to `off`, or to an http or https address, or unset it. |

## The shared graph

| It says | What to do |
|---|---|
| "kelve couldn't reach the shared graph. Try again in a moment." | Check you're online, then try again. |
| "The shared graph doesn't know this kelve any more. Sign in to it again." | Sign in again, in **Settings**, **The shared graph**. |
| "This kelve's graph key is set where it runs (KELVE_GRAPH_KEY), and that one wins. …" | Change or remove `KELVE_GRAPH_KEY` where kelve runs, then run `kelve stop`. |
| "This kelve has no shared graph to sign in to." | `KELVE_GRAPH_URL` is `off`. Unset it to use the shared graph. |

## Entries wait until tomorrow

The shared graph takes only so much from an account a day. kelve sends the rest when its day begins again, at midnight UTC. **Settings**, **The shared graph**, **Sent today** says when.

## A lesson hasn't gone

A lesson your agent learns waits a day before it goes, so you can stop it. **Settings**, **Lessons** says when each leaves.

## Something went wrong in kelve

kelve keeps a short report when it stops unexpectedly, or when its page meets an error. The report holds no secrets, no file names and nothing you opened. **Settings**, **What's shared** shows each report. You can choose **Report it on GitHub**, where you read it again before it's posted. Or you can forget it.

## Still stuck

[Report a problem](https://github.com/kelve-ai/kelve/issues/new) on GitHub, with what kelve said and what you ran. Leave out anything from your work you don't want public.
