---
title: Troubleshooting
url: https://arcana.otnelhq.com/docs/troubleshooting
---

# 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:



| Provider | Key Format |
| --- | --- |
| OpenAI | `sk-proj-...` or `sk-...` |
| Anthropic | `sk-ant-...` |
| DeepSeek | `sk-...` (32+ chars) |
| OpenRouter | `sk-or-...` |




### 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](/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/Enterprise license.




## 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
```