Skip to content
Katachi

Troubleshooting

Installation Issues

Section titled “Installation Issues”

cloudflared download failed

Section titled “cloudflared download failed”
[katachi] ⚠ Failed to download cloudflared after 3 attempts

Fix: Retry the download:

Terminal window
npm rebuild @katachi/agent

If that doesn’t work, install cloudflared manually and set CLOUDFLARED_SKIP=1:

Terminal window
# macOS
brew install cloudflared


# Windows
winget install Cloudflare.cloudflared


# Linux (Debian/Ubuntu)
curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-archive-keyring.gpg] https://pkg.cloudflare.com/cloudflared any main' | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install cloudflared

katachi command not found after install

Section titled “katachi command not found after install”

Windows (PowerShell): Close and reopen your terminal after npm install -g. npm’s global bin directory may not be in your PATH for the current session.

Linux/macOS: Ensure npm’s global bin directory is in your PATH:

Terminal window
export PATH="$(npm config get prefix)/bin:$PATH"

Agent Issues

Section titled “Agent Issues”

Agent won’t start

Section titled “Agent won’t start”
✗ Katachi agent failed to start

Common causes:

  1. Port conflict — Another process is using port 7676:

    Terminal window
    katachi start --port 3001

  2. Stale process — A previous agent didn’t clean up:

    Terminal window
    katachi stop
    katachi start

  3. Missing credentials — If credentials are corrupted:

    Terminal window
    katachi unregister --force
    katachi start

Agent shows “offline” in web UI

Section titled “Agent shows “offline” in web UI”

Check agent status:

Terminal window
katachi status

Common causes:

  1. Agent not running — Start it with katachi start
  2. Network issue — Ensure outbound HTTPS (port 443) is allowed
  3. Tunnel reconnecting — Wait 30 seconds; cloudflared auto-reconnects

High memory usage

Section titled “High memory usage”

The agent loads AI SDKs on demand. If memory usage is excessive:

Terminal window
katachi restart

Authentication Issues

Section titled “Authentication Issues”

Device flow times out

Section titled “Device flow times out”

Fix: Make sure you’re visiting the correct URL and entering the code within 15 minutes. If it expires, stop and restart the agent:

Terminal window
katachi stop
katachi start

“Unauthorized” errors in web UI

Section titled ““Unauthorized” errors in web UI”

Common causes:

  1. Session expired — Log out and log back in at katachi.live
  2. Subscription inactive — Check your subscription status in Settings

Getting More Help

Section titled “Getting More Help”
  1. Check logs: katachi logs -f
  2. Enable debug mode: katachi start --debug
  3. Contact support: [email protected]

Git Sync Issues

Section titled “Git Sync Issues”

Git Authentication

Section titled “Git Authentication”

If the agent loses access to your repository or fails to pull/push:

  1. Check local git credentials — Make sure you can pull from the terminal manually.
  2. SSH keys — If using SSH, ensure ssh-agent is running or keys don’t require passwords.

Diverged Branches

Section titled “Diverged Branches”

When your local agent’s branch and the remote branch diverge (e.g., after a force push or editing on multiple machines):

  1. Manual intervention — Open your terminal and resolve it manually:
    Terminal window
    git pull --rebase
    # Or reset
    git reset --hard origin/your-branch
  2. Continue — Return to the UI and click “Continue with local”.