docs/TROUBLESHOOTING.md

Troubleshooting

“Token data is not available.” (Codex CLI)

Common causes:

• The container wasn’t restarted after setting Secrets.
• The auth file wasn’t written to ~/.codex/.auth.json.

In the terminal, check:

• ls -la ~/.codex
• cat ~/.codex/.auth.json

If you use env-based token auth, set one of:

• CODEX_ID_TOKEN or ID_TOKEN
• CODEX_ACCESS_TOKEN or ACCESS_TOKEN
• CODEX_REFRESH_TOKEN or REFRESH_TOKEN
• optional CODEX_ACCOUNT_ID or ACCOUNT_ID

Notes:

• You do not need to provide last_refresh as a Secret; it is written automatically.

Gemini / Claude CLI authentication

This repo prefers env-based auth for provider CLIs (keep tokens out of git and UI):

• Gemini: GEMINI_API_KEY
• Claude: ANTHROPIC_API_KEY

RAG endpoints return 403 (“Indexing is disabled”)

Set ENABLE_INDEXING=1 in your environment and restart the container.

Website indexing fails (“Host is not allowed”)

Website indexing blocks private/localhost targets to reduce SSRF risk. Use a public http(s) URL and keep indexing within the same origin.

GitHub indexing fails for private repos

Set GITHUB_TOKEN (or GITHUB_PAT) as an environment variable / HF Secret, then retry.

Terminal shows vertical/1-column text

This usually means the terminal “fit” ran while the terminal view was hidden or at size 0.

Mitigations:

• Switch to the Terminal view after the page fully loads.
• Resize the browser window once to trigger a refit.

MCP “Test” fails even though the server is up

The Settings → MCP “Test” button runs from your browser, so it is subject to CORS and network access from the client.

Also note:

• mcp.json import only accepts http:// / https:// URLs.
• If MCP tool calls are blocked, check Settings → MCP → Tool Policy (server-enforced allow/deny list).

API errors are shown as JSON

The backend returns a consistent error payload like: {"detail":"...","error":{"code":"...","message":"...","status":...,"details":...}}.

PTY allocation failed

If the backend prints PTY allocation failed, the runtime likely lacks /dev/pts or has exhausted PTYs.

HF Spaces generally supports PTYs, but custom runtimes may not.

Rooms returns 403 (“Rooms are disabled”)

Set ENABLE_ROOMS=1 in your environment and restart the container.

Admins can also toggle feature overrides from Settings → Admin.

P2P isn’t connecting in Rooms

The Rooms view uses WebRTC DataChannels (optional, behind “Prefer P2P”). Some networks block UDP/WebRTC. If P2P fails, keep “Prefer P2P” off and it will use server WebSockets for messaging.

Password reset emails aren’t arriving

Supabase email delivery depends on your project auth settings and SMTP configuration.

Check:

• Supabase → Authentication → Providers → Email is enabled
• Supabase → Authentication → URL Configuration:
  • Site URL points to your deployment
  • Redirect URLs includes your /login URL
• Supabase → Authentication → SMTP Settings: configure a real SMTP provider for reliable delivery

Also check Supabase Auth logs for send failures and your inbox spam/quarantine.

Password recovery link opens but “Update password” fails

Supabase recovery links can be either:

• hash tokens (#access_token=...&refresh_token=...&type=recovery)
• PKCE code (?code=...)

This app calls supabase.auth.getSessionFromUrl({ storeSession: true }) to consume either format, then calls updateUser().

If it still fails:

• Verify the link points to your deployed /login URL.
• Verify Supabase Auth → URL Configuration includes your /login redirect URL.

Vault is disabled

Set ENABLE_VAULT=1 and restart the container (admins can also toggle the Vault feature override).