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 default

Authentication & Key Issues

"Invalid API key" error

Your provider API key may be incorrect, expired, or for the wrong provider:

# Re-add the key
arcana key add openai <your-key>

# Test the key
arcana key test openai

# List configured keys to verify
arcana key 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:

# Check your session token
arcana session token

# Verify your account 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 --verbose

Proxy returns errors (500, 502, 503)

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

Memory Issues

Slow memory search

The FTS5 search index may need rebuilding, especially after importing a large memory export:

arcana memory rebuild-index

Cloud sync fails

# Ensure cloud sync is enabled
arcana config get memory.cloudSync

# Check sync status
arcana memory sync-status

# Force a full push
arcana memory push --force

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 daily usage
arcana credits 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