Skip to content
Kairo
Docs / Troubleshooting

Reference

Troubleshooting

Every error the CLI prints comes with a hint on the line below it. Here's what each common one means and how to fix it.

Installing#

EACCES: permission denied during npm install -g

npm error code EACCES
npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/kairo-cli'

This isn’t specific to Kairo. It happens on macOS and Linux when Node was installed from the nodejs.org installer or a system package: npm’s global folder belongs to the system, so your user account can’t write to it. Point npm at a folder in your home directory instead, once:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g kairo-cli

If you use bash rather than zsh, write to ~/.bashrc instead of ~/.zshrc. Then check it worked with kairo --version. Every global package you install from now on goes in the new folder as well.

Alternatively, install Node with a version manager such as nvm, which keeps global packages in your home directory from the start. Avoid sudo npm install -g: it works, but it leaves root-owned files behind that cause the same error later.

Installed, but kairo: command not found

zsh: command not found: kairo

npm installed the package into a folder your shell doesn’t look in. Find the folder with npm prefix -g; the kairo command is in its bin subfolder, and that has to be on your PATH. After changing ~/.zshrc, open a new terminal or run source ~/.zshrc.

If source ~/.zshrc prints an error, the file stopped at that line and nothing after it ran — including a PATH line you just added at the end. Fix the line it names, then run it again.

Signing in#

You're not signed in

✗ You're not signed in.
  Run `kairo login` to connect this machine to your Kairo account.

This machine has no stored sign-in. Run kairo login and approve the code in your browser. See Authentication.

That sign-in is no longer valid

✗ That sign-in is no longer valid.
  Run `kairo login` to sign in again.

The token expired (after 90 days) or was revoked. The CLI has already removed it; run kairo login again. If you use KAIRO_TOKEN, the hint says so — replace that token.

The code expired, or the sign-in was denied

✗ The code expired before it was approved.
  Run `kairo login` again for a fresh one.

Codes last 15 minutes. You’ll see That sign-in was denied in the browser if Deny was clicked, or Timed out waiting for the browser if the CLI stopped waiting. In every case, run kairo login again.

The browser didn’t open

The CLI prints the URL under If nothing opened. Open it on any device, sign in to Kairo, enter the code shown in your terminal and click Approve.

Your repository#

Repository isn't connected

✗ ada/lighthouse isn't connected to a Kairo project you own.
  Connect it on your project's page in Kairo, under Repository.

Kairo couldn’t match this repository to one of your projects. Check, in order:

  1. The project has this repository connected. On the project’s page, click Connect repository and choose it.
  2. You’re signed in as the project’s owner: kairo whoami.
  3. Your origin remote is the same repository (git remote -v). A fork has a different name from the repository you connected.

No origin remote, or not a GitHub repository

✗ This repository has no `origin` remote.
  Kairo finds your project by its GitHub remote. Add one with `git remote add origin …`.

Kairo identifies your repository by its origin remote, and only GitHub remotes are supported. If origin points somewhere else, you’ll see Kairo doesn’t recognise … as a GitHub repository.

git remote add origin https://github.com/ada/lighthouse.git

Not a git repository, or no commits yet

✗ This folder isn't a git repository.
  Run `kairo review` from inside your project, or start one with `git init`.

Run the command from inside your project, or pass its path with kairo review -C ~/code/lighthouse. In a brand-new repository you’ll see This repository doesn’t have any commits yet — make a commit first.

Generating a draft#

AI unavailable

✗ Kairo's AI writer is unavailable right now.
  Kairo had a problem at its end. Try again in a moment.

The AI model behind Kairo couldn’t write a draft. Nothing was saved or published. Wait a moment and run kairo review again. You may also see:

  • Kairo’s AI writer is busy. Try again in a moment.
  • Writing that draft took too long.
  • The AI writer answered with something Kairo couldn’t read.

All are temporary — try again.

Too many drafts

✗ You've asked for a lot of drafts just now.
  Give it a minute and run `kairo review` again.

Drafts are rate-limited per account. Wait a minute. Reopening a saved draft doesn’t count — only generating a new one does.

Couldn't reach Kairo

✗ Couldn't reach Kairo at https://joinkairo.vercel.app.
  Check your connection, or set KAIRO_API_URL if you meant another server.

The CLI got no answer at all. Check your connection. If you set KAIRO_API_URL, check it points at the right server.

Publishing#

Could not publish

✗ Could not publish that build log.
  Kairo had a problem at its end.

  Your draft is still here. Press P to try again, or E to change it.

Your draft is still on screen. Press P to try again — it’s safe, as Kairo never creates two build logs for the same commit. If the connection dropped, the message is Couldn’t reach Kairo and the fix is the same.

The draft was refused

✗ Title: Give the build log a title of at least 3 characters.
  Press E to change the draft.

The draft breaks a build log rule. Titles need 3–120 characters and summaries 10–5,000. Press E, fix it, and publish again. See Editing a draft.

Profile not set up

✗ Finish setting up your Kairo profile before publishing.
  Pick a username on Kairo, then run `kairo review` again.

Every build log links to its author’s profile, so you need a username. Finish setting up your profile on the website, then run kairo review — your draft is still saved.

The terminal#

The terminal closed mid-review

Nothing was lost. Open a terminal in the same repository and run kairo review — you’ll see Found an existing draft for this commit. See Draft recovery.

“Not a terminal, so nothing was published”

kairo review ran without a terminal to ask you — in CI or with its output piped — so it only printed the draft. Run it in an interactive terminal to publish.

The post-commit hook#

No review after a commit

The hook deliberately skips the review when:

  • kairo isn’t on your PATH — it prints kairo: not found on PATH. Install it globally with npm install -g kairo-cli.
  • You committed from an editor’s commit button, or anywhere without a terminal.
  • A rebase or cherry-pick was in progress.
  • KAIRO_SKIP_HOOK=1 is set in your environment — check it isn’t left over.

You can always run kairo review by hand afterwards. Running kairo install again shows which hook file it uses.

Your hook is in another language

✗ .git/hooks/post-commit is a python script, so Kairo left it alone.
  Have it run `kairo review` after its own work, or switch it to a shell script and run `kairo install` again.

Kairo only adds itself to shell hooks. Call kairo review at the end of your own hook instead.

Kairo's section of the hook was edited

✗ Kairo's section of .git/hooks/post-commit has been edited, so it wasn't changed.
  Delete the lines between the `kairo post-commit` markers, markers included, and run the command again.

Do what the hint says, then run the command again.

Something went wrong inside the Kairo CLI#

This message, followed by a stack trace, means you’ve found a bug in the CLI rather than a problem with your setup. Your commit is unaffected. Please report it with the stack trace and the output of kairo --version.