Documentation Index
Fetch the complete documentation index at: https://kagi.micr.dev/llms.txt
Use this file to discover all available pages before exploring further.
Error Reference
This guide catalogs all error messages from the kagi CLI, organized by category with explanations and solutions.
Errors follow this pattern:
Error: {category}: {message}
Error: missing credentials - this command requires KAGI_SESSION_TOKENError: Auth error: Kagi Search API request rejected: HTTP 403 Forbidden
Authentication Errors
”missing credentials”
Message:
Config error: missing credentials: set KAGI_API_TOKEN or KAGI_SESSION_TOKEN (env), or add [auth] api_token/session_token to .kagi.toml
# Set session token
kagi auth set --session-token 'https://kagi.com/search?token=YOUR_TOKEN'
# Or set API token
kagi auth set --api-token 'YOUR_API_TOKEN'
# Verify
kagi auth check
“this command requires KAGI_SESSION_TOKEN”
Message:
Config error: this command requires KAGI_SESSION_TOKEN (env or .kagi.toml [auth.session_token])
# Add session token
kagi auth set --session-token 'https://kagi.com/search?token=YOUR_TOKEN'
# Or if using wrong mode
kagi summarize --subscriber --url https://example.com # Use --subscriber for session
kagi quick "what is rust"
kagi assistant "Explain Rust ownership"
“this command requires KAGI_API_TOKEN”
Message:
Config error: this command requires KAGI_API_TOKEN (env or .kagi.toml [auth.api_token])
# Add API token
kagi auth set --api-token 'YOUR_API_TOKEN'
# Or remove conflicting flag
kagi summarize --url https://example.com # Remove --subscriber for API mode
“auth check failed”
Message:
Error: Auth error: Kagi Search API request rejected: HTTP 403 Forbidden
- Token expired
- Token revoked
- Token regenerated in Kagi settings
- Account doesn’t have required access
Solution:
- Log into kagi.com
- Navigate to Settings → Account (session) or API
- Generate new token
- Update configuration:
*kagi* auth set --session-token 'NEW_TOKEN'
# or
*kagi* auth set --api-token 'NEW_API_TOKEN'
- Verify:
kagi auth check
”Insufficient credit”
Message:
Error: Auth error: Kagi Search API request rejected: HTTP 400 Bad Request; Insufficient credit
- Check API credit in Kagi settings
- Add credit if needed
- Or use subscriber features (no credit required)
Configuration Errors
”Config file not found”
Message:
Meaning: No configuration file exists yet.
Solution:
This is informational. Run kagi auth set to create it, or use environment variables.
”quick query cannot be empty”
Message:
configuration error: quick query cannot be empty
kagi quick received an empty string after trimming whitespace.
Solution:
kagi quick "what is rust"
“Permission denied”
Message:
Error: Permission denied (os error 13)
# Check permissions
ls -la ./.kagi.toml
# Fix permissions
chmod 600 ./.kagi.toml
# Or recreate
rm ./.kagi.toml
kagi auth set --session-token 'YOUR_TOKEN'
“translate bootstrap did not mint a translate_session cookie”
Meaning: The translate site accepted the request but did not issue the session cookie the CLI needs for follow-on API calls.
Likely causes:
KAGI_SESSION_TOKEN is invalid or expired- the current Kagi account state no longer authorizes Translate
- Kagi changed the bootstrap cookie behavior
Solution:
# refresh and save the current Session Link
kagi auth set --session-token 'https://kagi.com/search?token=...'
# verify the token still works for subscriber features
kagi auth check
# retry translate
kagi translate "Bonjour tout le monde"
Command Errors
”search filters require KAGI_SESSION_TOKEN”
Message:
Config error: search filters require KAGI_SESSION_TOKEN (env or .kagi.toml [auth.session_token])
--region, --time, --from-date, --to-date, --order, --verbatim, or personalization flags without a configured session token.
Solution:
# Add a session token
kagi auth set --session-token 'https://kagi.com/search?token=YOUR_TOKEN'
# Or remove the session-only search filters
kagi search "rust release notes"
“search —time cannot be combined with —from-date or —to-date”
Meaning: Kagi’s live search UI treats preset time windows and custom date ranges as separate filter modes.
Solution:
# Use a preset time window
kagi search --time month "rust release notes"
# Or use a custom date range
kagi search --from-date 2026-01-01 --to-date 2026-03-01 "rust release notes"
kagi search --from-date 2026-03-01 --to-date 2026-03-19 "rust compiler"
“—length requires —subscriber”
Message:
Error: Config: --length requires --subscriber
--length option only works with subscriber summarizer mode.
Solution:
# Add --subscriber flag
kagi summarize --subscriber --url https://example.com --length digest
“lens ‘abc’ must be a numeric index”
Message:
configuration error: lens 'abc' must be a numeric index (e.g., '0', '1', '2').
l= value from Kagi’s web UI.
Solution:
# Search
kagi search --lens 2 "developer documentation"
# Quick Answer
kagi quick --lens 2 "best rust tutorials"
“—engine is only supported for the paid public summarizer API”
Message:
Error: Config: --engine is only supported for the paid public summarizer API
--engine option doesn’t work with subscriber mode.
Solution:
# Remove --subscriber for API mode
kagi summarize --url https://example.com --engine cecil
“—cache is only supported for the paid public summarizer API”
Message:
Error: Config: --cache is only supported for the paid public summarizer API
--cache option doesn’t work with subscriber mode.
Solution:
# Remove --subscriber flag
kagi summarize --url https://example.com --cache false
“translate —to cannot be ‘auto’; pass an explicit target language code”
Message:
configuration error: translate --to cannot be 'auto'; pass an explicit target language code
kagi translate "Bonjour tout le monde" --to en
kagi translate "Bonjour tout le monde" --to ja
“—url or —text required”
Meaning: Summarize command needs content to summarize.
Solution:
# Provide URL
kagi summarize --url https://example.com
# Or text
kagi summarize --text "Content to summarize..."
“invalid ask-page URL”
Message:
Config error: invalid ask-page URL: relative URL without a base
kagi ask-page requires an absolute http or https URL.
Solution:
kagi ask-page https://example.com "What is this page about?"
“ask-page URL must use http or https”
Message:
Config error: ask-page URL must use http or https, got `file`
ask-page.
Solution:
Use a normal web URL, or ask the question through a different command surface.
”ask-page question cannot be empty”
Message:
Config error: ask-page question cannot be empty
kagi ask-page https://example.com "Give me the main argument in one sentence"
Network Errors
”Network error: request to Kagi timed out”
Meaning: Request took too long to complete.
Causes:
- Slow internet connection
- Kagi service slow
- Rate limiting
Solution:
- Check internet connection
- Try again later
- Add retry logic:
for i in 1 2 3; do
*kagi* search "query" && break
sleep 5
done
“Failed to connect”
Meaning: Cannot establish connection to Kagi.
Causes:
- No internet
- DNS failure
- Firewall/proxy blocking
Solution:
# Test connectivity
ping kagi.com
nslookup kagi.com
curl -I https://kagi.com
# Check proxy settings
env | grep -i proxy
# Try without proxy temporarily
unset HTTPS_PROXY
kagi search "test"
“DNS resolution failed”
Meaning: Cannot resolve kagi.com hostname.
Solution:
# Test DNS
nslookup kagi.com
dig kagi.com
# Try public DNS temporarily
echo 'nameserver 8.8.8.8' | sudo tee /etc/resolv.conf
“SSL/TLS error”
Meaning: Certificate validation failed.
Causes:
- System time wrong
- Outdated CA certificates
- Corporate proxy
Solution:
# Check time
date
# Update certificates
# Ubuntu/Debian:
sudo apt-get update && sudo apt-get install -y ca-certificates
# macOS:
brew install ca-certificates
Parse Errors
”failed to serialize search response”
Meaning: Response couldn’t be parsed as JSON.
Causes:
- API returned unexpected format
- Version mismatch
- Corrupted response
Solution:
- Update kagi CLI:
curl -fsSL https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.sh | sh
- Check raw output:
*kagi* search "test" 2>&1 | head -20
“failed to parse”
Meaning: General parsing error.
Solution:
# Check version
kagi --version
# Update to latest
# (reinstall using install script)
Rate Limit Errors
”Rate limit exceeded”
Meaning: Too many requests in short time.
Solution:
- Wait a few minutes
- Add delays between requests:
for url in $URLS; do
*kagi* summarize --subscriber --url "$url"
sleep 2
done
- Reduce request frequency
”Too many requests”
Same as rate limit. Wait and retry with slower pace.
Installation Errors
”command not found”
Meaning: kagi not in PATH.
Solution:
# Find binary
which kagi || find ~ -name "kagi" -type f 2>/dev/null
# Add to PATH
export PATH="$HOME/.local/bin:$PATH"
# Or open new terminal
“No such file or directory”
Meaning: Binary missing or wrong path.
Solution:
Reinstall using install script or package manager.
Exit Codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | Any error (check stderr) |
Debugging Strategy
Step 1: Check Basic Functionality
kagi --version # Binary works?
kagi --help # Shows help?
kagi news --limit 1 # Network works?
Step 2: Check Authentication
kagi auth status # What's configured?
kagi auth check # Does it work?
Step 3: Isolate the Issue
# Test specific command
kagi search "test" 2>&1
# Check raw output
kagi search "test" 2>&1 | cat
Step 4: Check Environment
# Auth tokens
echo $KAGI_SESSION_TOKEN
echo $KAGI_API_TOKEN
# Network
env | grep -i proxy
curl -I https://kagi.com
# System
uname -a
kagi --version
Getting Help
If you encounter an error not listed here:
- Check Troubleshooting
- Search GitHub Issues
- Create new issue with:
- Error message (exact text)
- Command you ran
- kagi version (
kagi --version)
- OS and version
