Troubleshooting

Common issues and how to resolve them.

Installation Issues

npm i -g @axplusb/kepler fails

Cause: Permission error or missing dependencies.

Fix:

# Use nvm to avoid permission issues
nvm use 22
 
# Or install with sudo (macOS/Linux)
sudo npm i -g @axplusb/kepler
 
# Or fix npm permissions
npm config set prefix ~/.npm-global
export PATH="$PATH:~/.npm-global/bin"

kepler: command not found

Cause: The npm global bin directory isn’t in your PATH.

Fix:

# Add npm global bin to PATH
echo 'export PATH="$PATH:$(npm bin -g)"' >> ~/.zshrc
# or ~/.bashrc
source ~/.zshrc

Authentication Issues

Browser doesn’t open for OAuth

Cause: Headless environment or missing browser.

Fix: The CLI prints a URL. Open it manually in any browser.

→ If the browser didn't open, visit:
  https://bahulam.ai/auth/cli?code=...

Authentication failed or Token expired

Cause: Your session token has expired or was revoked.

Fix:

# Log out and re-authenticate
# Delete the cached session
rm -rf ~/.kepler/auth
kepler

Model & API Issues

Model not available or Insufficient credits

Cause: The selected model isn’t available on your plan, or you’re out of credits.

Fix:

• Switch to a model available on your plan (see Choosing a Model)
• Top up credits in the Settings → Billing page
• Configure a BYOK key to bypass credit usage

BYOK model not working

Cause: The API key is invalid, expired, or doesn’t have access to the selected model.

Fix:

1. Verify your key is correct in Settings → API Keys
2. Check that the provider supports the model you selected
3. Try setting the key as an environment variable:

   export OPENROUTER_API_KEY="sk-or-v1-..."
   kepler

Rate limit exceeded

Cause: Too many requests in a short period.

Fix:

• Wait a few seconds and retry
• Reduce the frequency of rapid-fire commands
• If using BYOK, check your provider’s rate limits

Project Issues

Kepler doesn’t understand my project structure

Cause: Project indexing didn’t complete, or the project has an unusual structure.

Fix:

# Force re-index
kepler --no-index  # start without index
# Then in the REPL:
/reindex

.kepler/ folder issues

Cause: Corrupted session history or workspace state.

Fix:

# Reset Kepler's local state for this project
rm -rf .kepler/
kepler

Changes aren’t being applied

Cause: File permissions, git working tree issues, or Kepler is in read-only mode.

Fix:

• Ensure the file is writable
• Check that you’re not in a detached HEAD state in git
• Verify you’re in the correct directory

Performance Issues

Kepler is slow

Cause: Large project, slow model, or network latency.

Fix:

• Use a faster model (DeepSeek V4 Flash, Claude Haiku)
• Narrow the scope of your request
• Use /plan to reduce wasted turns
• Check your internet connection

High credit usage

Cause: Long context windows, large files, or verbose models.

Fix:

• Use cheaper models for exploration
• Keep requests focused and specific
• Configure a cheaper explorer model in Settings → Models
• Enable BYOK to use your own provider billing

Error Messages

Getting Help

If you’re still stuck:

• Check the dashboard — bahulam.ai for account status, billing, and active sessions
• Run with --debug — kepler --debug produces verbose logs that help diagnose issues
• File an issue — on the GitHub repo