Troubleshooting

arcana doctor

The arcana doctor command checks your system health — config, API keys, cache files, and runtime environment.

arcana doctor

This will report:

• Config — whether ~/.arcana/config.json exists and is valid JSON
• API keys — which provider keys are detected (OpenAI, Anthropic, Gemini, etc.)
• Cache — skills cache, model catalog, and other cached data
• Runtime — Node/Bun version, platform, and shell
• License — active license status (if paired with console)

# Check if the web app is healthy
arcana doctor --web

Common issues

No API key detected

Symptom: Arcana says "no provider available" or refuses to start a session.

Fix: Set a provider key as an environment variable:

export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...
# or
export GEMINI_API_KEY=...

# Verify detection
arcana doctor

You can also set apiKey in ~/.arcana/config.json, but environment variables are preferred for security.

Console login fails

Symptom: Device flow doesn't complete, or the browser shows an error.

Fix:

1. Ensure you have internet access and can reach arcana.otnelhq.com.
2. Try arcana console login again — the device code expires after ~10 minutes.
3. Check that you completed sign-in on the correct browser tab.
4. If on a shared machine, ensure no one else has arcana console logout'd your session.

Workspace trust not loading

Symptom: Project plugins, custom tools, or local MCP are not loaded.

Fix:

# Trust the current workspace
arcana trust

# Check trust status
arcana trust status

# List all trusted workspaces
arcana trust list

# Revoke trust (re-trust will re-fingerprint)
arcana trust revoke

Trust is invalidated when executable project config changes. Re-run arcana trust after updating project plugins or tools.

Gateway not starting

Symptom: arcana gateway exits immediately or shows "allowlist required".

Fix: Every platform requires an allowlist. Add allowed users or channels to your config:

{
  "gateway": {
    "telegram": { "token": "111:xxx", "allowedUsers": ["12345678"] }
  }
}

For local development only, you can bypass allowlists:

export ARCANA_GATEWAY_OPEN=1
arcana gateway

Cron jobs not running

Symptom: Scheduled jobs don't execute at the expected time.

Fix:

1. Start the cron daemon: arcana cron start
2. Check job status: arcana cron list — ensure the job is enabled, not paused.
3. Run a job manually to test: arcana cron run --id <job-id>
4. Verify your API key is set — cron jobs use your configured provider.

arcana serve requires password

Symptom: arcana serve fails when binding to a non-loopback address.

Fix: Non-loopback binds require ARCANA_SERVER_PASSWORD:

export ARCANA_SERVER_PASSWORD=my-secret
arcana serve --hostname 0.0.0.0 --port 4096

Memory search returns no results

Symptom: arcana memory search returns empty results despite having sessions.

Fix:

• Ensure memory is enabled: "memory": { "enabled": true } in config.
• Check the database exists: ls ~/.arcana/data/memory.db
• Try a broader query — FTS5 requires at least 2 characters per token.
• Run arcana memory stats to see how many sessions and facts are stored.

Theme not applying

Symptom: Changing theme in config doesn't reflect in the TUI.

Fix:

• Restart Arcana after changing ~/.config/arcana/tui.json.
• Use the in-TUI picker: press ⛧ themes for live preview.
• Verify the theme name is valid: arcana, bloodmoon, coven, crypt, dragon, lich, wraith.

FAQ

Does Arcana sell API access?

No. Arcana works with your own provider keys (BYOK). Model costs stay with your provider. Arcana charges only for the terminal layer, memory services, sync, and team features.

Is Arcana free?

Yes. The local CLI with your own API keys is free. Pro ($19/mo) adds unlimited provider keys, advanced memory search, multi-model rooms, and cost tracking. Enterprise adds encrypted sync, gateway relay, and team features.

What is the proxy?

The proxy (proxy.arcana.otnelhq.com) is an OpenAI-compatible HTTP API that routes requests through your Arcana license. It adds memory, tools, and session tracking on top of raw model calls. You can also use your own provider keys directly — the proxy is optional.

Which models are supported?

Arcana supports OpenAI, Anthropic, Google Gemini, Amazon Bedrock, Cloudflare Workers AI, xAI (Grok), OpenRouter, Cerebras, Ollama, and any custom OpenAI-compatible endpoint. Use arcana models to list available models.

Where does Arcana store data?

All local data lives under ~/.arcana/ — sessions, memory, config, and trust records. Override with ARCANA_HOME. No data is sent to Arcana's servers unless you explicitly enable cloud sync.

Is Arcana secure?

Arcana runs locally by default. Workspace trust gates project plugins and tools. The server requires a password for non-loopback binds. Gateway adapters enforce allowlists. See the security section for details.

How do I upgrade?

arcana upgrade

Or reinstall from npm:

npm install -g arcana-ai@latest

Dev escape hatches

These environment variables are for development and debugging only. Do not use in production.

Getting help

• Run arcana doctor to diagnose issues automatically.
• Check the main docs for feature references.
• Visit the changelog for recent fixes and updates.
• Open an issue on GitHub for bugs.