Troubleshooting

Common issues when using Arcana and how to resolve them. If you don't find your issue here, try running arcana --verbose to enable debug output.

Installation Issues

npx arcana-ai@latest fails

This usually means Node.js is not installed or is out of date. Arcana requires Node.js 18+.

# Check your Node.js version
node --version

# If below v18, upgrade:
nvm install node --latest    # if using nvm
# or download from https://nodejs.org

Permission errors when installing

# On macOS/Linux, if you get EACCES errors:
npm install -g arcana-ai
# Or use npx without global install:
npx arcana-ai@latest

Windows-specific issues

Arcana works on Windows via PowerShell, CMD, or WSL. Ensure you're using a truecolor terminal like Windows Terminal:

# If theme colors don't display correctly:
# 1. Use Windows Terminal (not the legacy console host)
# 2. Enable truecolor in your terminal profile
# 3. Verify with: arcana theme preview arcana

Authentication & Key Issues

"Invalid API key" error

Your provider API key may be incorrect, expired, or for the wrong provider. Keys are set via environment variables — there is no key add command:

# Set or fix the key for your shell session
export OPENAI_API_KEY=sk-...

# Confirm Arcana detects it (shows last 4 chars)
arcana doctor

# List providers with detected credentials
arcana providers list

Ensure you're using the correct key format for each provider:

Proxy authentication fails

If you're using the Arcana proxy and getting 401/403 errors:

# Re-pair with the console (device flow)
arcana console login

# Check proxy account status
arcana proxy status

# Verify your license tier
arcana license status

Connection Issues

Network timeouts or connection refused

# Check if Arcana's servers are reachable
curl https://proxy-arcana.otnelhq.com/v1/health

# Check internet connectivity
ping proxy-arcana.otnelhq.com

# Try with verbose logging
arcana --print-logs --log-level DEBUG

Proxy returns errors (500, 502, 503)

These are usually temporary. Check the Arcana Status page for ongoing incidents.

Memory Issues

Slow or empty memory search

Check the memory store health and recompile learned knowledge:

# Inspect the local memory DB
arcana memory stats

# Recompile learned knowledge into facts
arcana memory compile

Cloud sync fails

# Run a full sync (push + pull) and watch for errors
arcana memory sync

# Or push/pull explicitly
arcana memory push
arcana memory pull

Cloud sync requires arcana console login and a Pro license or higher.

Performance Issues

Slow responses from the AI

• Try a faster model (e.g., gpt-4o-mini instead of gpt-4o)
• Reduce context size — large memory loads can slow down responses
• Check your internet connection speed

Unexpectedly high usage / rate limited

# Check your proxy usage and balance
arcana proxy usage
arcana proxy balance

# Upgrade your plan for higher limits
arcana license activate <license-key>

Debugging

Enable verbose logging to get more details about what Arcana is doing:

# Run with verbose output
arcana --verbose

# Set log level via environment variable
ARCANA_LOG_LEVEL=debug arcana

# Save logs to a file
arcana --verbose 2>&1 | tee arcana-debug.log