Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the kagi CLI. It’s organized by symptom and error message for quick reference.

Quick Diagnostic Steps

When encountering any issue, follow these steps first:

Check version: kagi --version
Verify installation: kagi --help
Test unauthenticated: kagi news --limit 1
Run the auth wizard on a TTY: kagi auth
Check auth status: kagi auth status
Validate credentials: kagi auth check

Reading Contextual Errors

Recent kagi builds include more context in failed HTTP operations. Use these details before retrying blindly:

HTTP 401 or HTTP 403 usually means the API token or session token was rejected. Run kagi auth and paste a fresh token from Kagi settings.
; response body: ... is a short server diagnostic. It can explain account state, insufficient credit, rate limits, or an expired session.
request to https://... identifies the Kagi surface that failed. This helps separate Search API issues from subscriber web-product issues.
batch query failed (N succeeded): query: error means only the listed batch entries failed. Retry those entries directly or lower --concurrency if the body mentions rate limits.

Installation Issues

”command not found” or “kagi is not recognized”

Symptoms:

Shell reports kagi: command not found
PowerShell reports kagi : The term '*kagi*' is not recognized

Causes:

Binary not in PATH
Shell not reloaded after installation
Installation didn’t complete

Solutions: 1. Find the binary:

# macOS/Linux
which kagi || find ~ -name "kagi" -type f 2>/dev/null

# Windows PowerShell
Get-ChildItem -Recurse -Filter "kagi.exe" -ErrorAction SilentlyContinue

2. Check if directory is in PATH:

# macOS/Linux
echo $PATH | tr ':' '\n' | grep -E '(local|bin)'

# Windows PowerShell
$env:PATH -split ';' | Select-String 'kagi'

3. Add to PATH manually:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload
source ~/.bashrc  # or ~/.zshrc

4. Open new terminal window (simplest solution for PATH issues)

Permission Denied (macOS/Linux)

Symptoms:

bash: /path/to/*kagi*: Permission denied

Solutions:

# Make executable
chmod +x ~/.local/bin/kagi

# Or reinstall via script which sets permissions automatically
curl -fsSL https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.sh | sh

Windows Defender / SmartScreen Blocks Installation

Symptoms:

“Windows protected your PC” dialog
“Unknown publisher” warning

Solutions:

Click “More info”
Click “Run anyway”
Consider adding exclusion for the kagi directory
Or use npm install as alternative: npm install -g kagi-cli

Installation Script Fails

Symptoms:

Script exits with error
“curl: (6) Could not resolve host”

Causes & Solutions: Network issues:

# Check connectivity
ping github.com

# Try with explicit DNS
curl --resolve raw.githubusercontent.com:443:185.199.108.133 \
  -fsSL https://raw.githubusercontent.com/... | sh

Corporate proxy:

# Set proxy for curl
export HTTPS_PROXY=http://proxy.company.com:8080
curl -fsSL https://raw.githubusercontent.com/... | sh

Download and run manually:

# Download script
curl -fsSL https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.sh -o install-kagi.sh

# Inspect (optional)
cat install-kagi.sh

# Run
sh install-kagi.sh

Authentication Issues

”missing credentials” Error

Symptoms:

configuration error: missing credentials: search was not sent. Set KAGI_API_KEY or KAGI_SESSION_TOKEN, or run `kagi auth set --api-key <key>` or `kagi auth set --session-token <token>`

Diagnostic:

# Check current status
kagi auth status

# Verify environment variable is set
echo $KAGI_SESSION_TOKEN
echo $KAGI_API_TOKEN

# Check for typos in variable name
env | grep KAGI

Solutions: 1. Set via environment variable:

export KAGI_SESSION_TOKEN='https://kagi.com/search?token=YOUR_TOKEN'

# Verify
kagi auth check

2. Set via config file:

kagi auth set --session-token 'https://kagi.com/search?token=YOUR_TOKEN'

# Or manually
mkdir -p ~/.config/kagi-cli
cat > ~/.config/kagi-cli/config.toml << 'EOF'
[auth]
session_token = "https://kagi.com/search?token=YOUR_TOKEN"
EOF

3. Common mistakes to check:

Variable name is KAGI_SESSION_TOKEN not KAGI_TOKEN
Using export not just assignment
No extra spaces around = in export
Token is complete (not truncated)

“auth check failed” Error

Symptoms:

Error: Auth error: Kagi Search API request rejected: HTTP 403 Forbidden

Causes:

Token is invalid or expired
Token was revoked
Account doesn’t have required access
Rate limit exceeded

Solutions: 1. Verify token in Kagi settings:

Log into kagi.com
Check Settings → Account (for session token)
Check Settings → API (for API token)
Ensure token hasn’t been regenerated

2. Regenerate if needed:

Generate new token in Kagi settings
Update your configuration
Test: kagi auth check

3. Check account status:

Verify subscription is active (for session token)
Verify API credit is available (for API token)

“this command requires KAGI_API_TOKEN”

Symptoms:

configuration error: this command requires KAGI_API_TOKEN. Set it in the environment or run `kagi auth set --api-token <token>`

Cause: Trying to use paid API commands without API token Solution:

# Add API token
kagi auth set --api-token 'your_api_token'

# Or use environment variable
export KAGI_API_TOKEN='your_api_token'

Note: API access is separate from your Kagi subscription and requires available credit.

Environment Variable Not Being Used

Symptoms:

Set env var but kagi auth status shows “not configured”
Config file values overriding env vars (opposite of expected)

Diagnostic:

# Check if variable is actually set
env | grep KAGI

# Check if exported
export -p | grep KAGI

# Try explicit command
KAGI_SESSION_TOKEN='token' kagi auth status

Common Causes: 1. Not exported:

# Wrong - just sets in current shell
KAGI_SESSION_TOKEN='token'

# Right - exports to environment
export KAGI_SESSION_TOKEN='token'

2. Subshell doesn’t inherit:

# Wrong - subshell doesn't see it
export KAGI_SESSION_TOKEN='token'
bash -c 'kagi auth status'

# Right - pass explicitly
bash -c 'kagi auth status'  # won't work
KAGI_SESSION_TOKEN='token' bash -c 'kagi auth status'  # works

3. Already set to empty:

# Unset first if having issues
unset KAGI_SESSION_TOKEN
unset KAGI_API_TOKEN

# Then set fresh
export KAGI_SESSION_TOKEN='token'

Session Link URL Not Working

Symptoms:

“Invalid token format” error
Authentication fails with session token

Solution: The CLI accepts both formats:

# Full URL (recommended)
kagi auth set --session-token 'https://kagi.com/search?token=abc123def456'

# Just the token
kagi auth set --session-token 'abc123def456'

Check URL format:

# Should contain 'token='
echo 'https://kagi.com/search?token=abc123' | grep -o 'token=[^&]*'

Command Execution Issues

”No results found” or Empty Output

Symptoms:

Command runs but returns empty data array
JSON shows { "data": [] }

Causes & Solutions: 1. Query is too specific:

# Try broader search
kagi search "python"  # instead of "python 3.12.1 specific error on macOS"

2. Rate limiting:

Wait a few minutes
Reduce request frequency
Check if both session token and API key are configured (fallback can help)

3. Network issues:

# Test connectivity
curl -I https://kagi.com

# Try with timeout
kagi search "test"  # should fail fast if network issue

JSON Parse Errors

Symptoms:

Error: failed to serialize search response

Causes:

Unexpected API response format
Binary version incompatible with API
Corrupted output

Solutions: 1. Update kagi:

# Check current version
kagi --version

# Update to latest
curl -fsSL https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.sh | sh

2. Test raw output:

# Check if output is valid JSON
kagi search "test" | jq . > /dev/null && echo "Valid JSON"

# If that fails, check what's happening
kagi search "test" 2>&1 | head -20

3. Clear any intermediaries:

# If using pipes, test direct output
kagi search "test" > /tmp/test.json
cat /tmp/test.json | jq .

Slow Response Times

Symptoms:

Commands take 10+ seconds to complete
Timeout errors

Causes & Solutions: 1. Network latency:

# Test connection speed
ping kagi.com

# Try different DNS
echo 'nameserver 8.8.8.8' | sudo tee /etc/resolv.conf

2. Fallback behavior:

Base search only falls back when you have opted into API-first mode with [auth.preferred_auth] = "api"
If the API path is slow or rejected, the session fallback adds delay
Leave base search on the default session-first behavior if you want to avoid that extra hop

3. Rate limiting backoff:

After many requests, service may slow responses
Add delays between requests: sleep 1

Command Hangs / No Output

Symptoms:

Command starts but never completes
No output, no error

Diagnostic:

# Run with timeout
timeout 30 kagi search "test"

# Check if process is stuck
ps aux | grep kagi

# Check network connections
netstat -an | grep 443

Solutions: 1. Interrupt and retry:

# Ctrl+C to cancel, then retry
kagi search "test"

2. Check network:

# Verify DNS resolves
nslookup kagi.com

# Test HTTPS
openssl s_client -connect kagi.com:443

3. Try different command:

# Test with simple command
kagi news --limit 1

Platform-Specific Issues

macOS: “Cannot be opened because the developer cannot be verified”

Symptoms:

Gatekeeper blocks execution
“macOS cannot verify that this app is free from malware”

Solutions: 1. Override for this instance:

Go to System Preferences → Security & Privacy → General
Click “Allow Anyway”
Re-run command

2. Remove quarantine attribute:

xattr -d com.apple.quarantine $(which kagi)

3. Disable Gatekeeper (not recommended):

sudo spctl --master-disable
# Re-enable after: sudo spctl --master-enable

Linux: “No such file or directory” despite file existing

Symptoms:

ls shows file exists
Running it gives “No such file or directory”

Cause: Missing dynamic libraries or incompatible binary Solutions: 1. Check library dependencies:

ldd $(which kagi)

# Look for "not found" entries

2. Use musl build (static):

# Download musl version instead of gnu
wget https://github.com/Microck/kagi-cli/releases/download/.../kagi-x86_64-unknown-linux-musl.tar.gz

3. Install missing libraries:

# Ubuntu/Debian
sudo apt-get install -y libssl-dev

# CentOS/RHEL
sudo yum install -y openssl-devel

Windows: PowerShell Execution Policy

Symptoms:

cannot be loaded because running scripts is disabled on this system

Solution:

# Check current policy
Get-ExecutionPolicy

# Set to allow signed scripts (recommended)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or bypass for this session (temporary)
powershell -ExecutionPolicy Bypass -File script.ps1

Network and Connectivity Issues

Corporate Proxy / Firewall

Symptoms:

Commands fail with network errors
Works on home network but not office network

Solutions: 1. Configure proxy:

# Set proxy environment variables
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# Or specific to kagi
export https_proxy=http://proxy.company.com:8080

2. Use package manager install: Package managers often respect system proxy settings better than curl downloads. 3. Manual download: Download release asset via browser, then install manually.

DNS Resolution Failures

Symptoms:

“Could not resolve host: kagi.com”
Works with IP but not hostname

Solutions:

# Test DNS
nslookup kagi.com
dig kagi.com

# Use public DNS temporarily
echo 'nameserver 8.8.8.8' | sudo tee /etc/resolv.conf

# Or in /etc/hosts (temporary)
echo '52.223.21.130 kagi.com' | sudo tee -a /etc/hosts

TLS / Certificate Errors

Symptoms:

SSL certificate verification failed
TLS handshake errors

Solutions: 1. Update CA certificates:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y ca-certificates

# macOS
brew install ca-certificates

# Update system certificates
sudo update-ca-certificates

2. Check system time:

# TLS requires correct time
date

# Sync time
sudo ntpdate pool.ntp.org

Performance Issues

High Memory Usage

Symptoms:

kagi process uses excessive memory
System slows down when using kagi

Causes & Solutions: 1. Large result sets:

# Limit results
kagi news --limit 5  # instead of --limit 100

2. Piping large data:

# Avoid loading entire results into memory
kagi search "test" | jq -r '.data[0:5]'  # limit early

Binary Size Concerns

The kagi binary is self-contained and includes:

Rust runtime
TLS certificates
HTTP client libraries

This makes it larger than simple scripts but ensures it works everywhere without dependencies. Size comparison:

kagi binary: ~5-10 MB
Equivalent Python + requests: ~50+ MB installed

Debugging Techniques

Enable Verbose Output

While kagi doesn’t have a --verbose flag, you can debug:

# Check what's being sent
curl -v https://kagi.com/...  # test endpoints directly

# Monitor network
sudo tcpdump -i any host kagi.com

# Trace execution
strace -f kagi search "test" 2>&1 | grep -E '(connect|send|recv)'

Test Authentication Directly

# Test current V1 API key
curl -H "Authorization: Bearer $KAGI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"test","limit":1}' \
  https://kagi.com/api/v1/search

# Test legacy V0 API token
curl -H "Authorization: Bot $KAGI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"test"}' \
  https://kagi.com/api/v0/fastgpt

Isolate Issues

Test components separately:

# 1. Binary works?
kagi --help

# 2. Auth configured?
kagi auth status

# 3. Auth valid?
kagi auth check

# 4. Unauthenticated commands work?
kagi news --limit 1

# 5. Session commands work?
kagi search "test"

# 6. API commands work?
kagi fastgpt "test"

Collect Debug Information

When reporting issues, include:

# System info
uname -a
kagi --version

# Auth status (redact tokens!)
kagi auth status | sed 's/token=.*/token=REDACTED/'

# Test commands
echo "=== Test 1: Help ==="
kagi --help
echo "=== Test 2: News ==="
kagi news --limit 1
echo "=== Test 3: Auth ==="
kagi auth check 2>&1 || echo "Auth check failed"

Error Reference Quick Guide

Error Message	Likely Cause	Solution
`command not found`	Not in PATH	Reload shell or add to PATH
`Permission denied`	Not executable	`chmod +x kagi`
`missing credentials`	No credential set	Set KAGI_SESSION_TOKEN, KAGI_API_KEY, or KAGI_API_TOKEN depending on the command
`kagi auth` needs an interactive terminal	Bare `kagi auth` was run in CI, a pipe, or another non-interactive environment	Use `kagi auth set`, `kagi auth status`, or `kagi auth check` instead
`auth check failed`	Invalid token	Regenerate token in Kagi settings
`403 Forbidden`	Auth issue	Check token validity
`No results found`	Empty query result	Try different query
`failed to serialize`	Version/API mismatch	Update kagi CLI

Getting Help

If you’ve tried the solutions above and still have issues:

Check GitHub Issues: github.com/Microck/kagi-cli/issues
Search existing issues for your error message
Create a new issue with:
- kagi version (kagi --version)
- Operating system and version
- Installation method
- Complete error message
- Steps to reproduce
- Debug output (with tokens redacted)

Common Gotchas

Token Confusion

Session Token: For subscriber features (lens, assistant)
API Key: For current paid API commands (search, extract)
Legacy API Token: For older paid API commands (fastgpt, summarize, enrich)
All three can exist, different commands need different ones

Bare `kagi auth` Fails in a Script

Symptom:

configuration error: `kagi auth` needs an interactive terminal. Use `kagi auth set`, `kagi auth status`, or `kagi auth check` in non-interactive environments

Cause: Bare kagi auth is the interactive onboarding wizard. It is meant for real terminals, not pipes or CI jobs. Fix: Use one of the explicit non-interactive subcommands:

kagi auth set --session-token 'https://kagi.com/search?token=...'
kagi auth status
kagi auth check

Variable Name Typos

KAGI_SESSION_TOKEN ✓
KAGI_SESSON_TOKEN ✗
KAGI_API_KEY ✓
KAGI_API_TOKEN ✓
KAGI_APITOKEN ✗

Config File Location

Default: ~/.config/kagi-cli/config.toml

The config file is resolved from $KAGI_CONFIG (an explicit full path), then $XDG_CONFIG_HOME/kagi-cli/config.toml, then ~/.config/kagi-cli/config.toml. A pre-existing ./.kagi.toml is no longer read; re-run kagi auth set (or kagi auth) to re-save credentials at the new location, or set KAGI_CONFIG to the old file path.

Shell Syntax

# Right
export KAGI_SESSION_TOKEN='token'

# Wrong - spaces around =
export KAGI_SESSION_TOKEN = 'token'

# Wrong - missing export
KAGI_SESSION_TOKEN='token'

Still stuck? Check the GitHub Issues or Discussions.

​Troubleshooting Guide

​Quick Diagnostic Steps

​Reading Contextual Errors

​Installation Issues

​”command not found” or “kagi is not recognized”

​Permission Denied (macOS/Linux)

​Windows Defender / SmartScreen Blocks Installation

​Installation Script Fails

​Authentication Issues

​”missing credentials” Error

​“auth check failed” Error

​“this command requires KAGI_API_TOKEN”

​Environment Variable Not Being Used

​Session Link URL Not Working

​Command Execution Issues

​”No results found” or Empty Output

​JSON Parse Errors

​Slow Response Times

​Command Hangs / No Output

​Platform-Specific Issues

​macOS: “Cannot be opened because the developer cannot be verified”

​Linux: “No such file or directory” despite file existing

​Windows: PowerShell Execution Policy

​Network and Connectivity Issues

​Corporate Proxy / Firewall

​DNS Resolution Failures

​TLS / Certificate Errors

​Performance Issues

​High Memory Usage

​Binary Size Concerns

​Debugging Techniques

​Enable Verbose Output

​Test Authentication Directly

​Isolate Issues

​Collect Debug Information

​Error Reference Quick Guide

​Getting Help

​Common Gotchas

​Token Confusion

​Bare kagi auth Fails in a Script

​Variable Name Typos

​Config File Location

​Shell Syntax

Troubleshooting Guide

Quick Diagnostic Steps

Reading Contextual Errors

Installation Issues

”command not found” or “kagi is not recognized”

Permission Denied (macOS/Linux)

Windows Defender / SmartScreen Blocks Installation

Installation Script Fails

Authentication Issues

”missing credentials” Error

“auth check failed” Error

“this command requires KAGI_API_TOKEN”

Environment Variable Not Being Used

Session Link URL Not Working

Command Execution Issues

”No results found” or Empty Output

JSON Parse Errors

Slow Response Times

Command Hangs / No Output

Platform-Specific Issues

macOS: “Cannot be opened because the developer cannot be verified”

Linux: “No such file or directory” despite file existing

Windows: PowerShell Execution Policy

Network and Connectivity Issues

Corporate Proxy / Firewall

DNS Resolution Failures

TLS / Certificate Errors

Performance Issues

High Memory Usage

Binary Size Concerns

Debugging Techniques

Enable Verbose Output

Test Authentication Directly

Isolate Issues

Collect Debug Information

Error Reference Quick Guide

Getting Help

Common Gotchas

Token Confusion

Bare `kagi auth` Fails in a Script

Variable Name Typos

Config File Location

Shell Syntax