Troubleshooting

Common issues you might encounter when running Frona AI, and how to fix them.

Services won’t start

Container exits immediately

Check the logs for the specific service:

docker compose logs frona

Common causes:

• Missing or invalid ANTHROPIC_API_KEY
• Invalid FRONA_AUTH_ENCRYPTION_SECRET
• Port conflict (another service is using 3001 or 3333)

Port conflicts

If a port is already in use, either stop the conflicting service or change the port mapping in docker-compose.yml:

ports:
  - "3002:3001"  # Map to a different host port

Browser automation not working

”Cannot connect to browser” errors

• Verify Browserless is running: docker compose ps browserless
• Check that FRONA_BROWSER_WS_URL is set correctly (default: ws://browserless:3333)
• Check Browserless logs: docker compose logs browserless
• Make sure you haven’t exceeded the concurrent session limit (default: 10)

Pages not loading in the browser

• Browserless needs outbound internet access
• Some sites block headless browsers. The agent can use request_user_takeover for these cases
• Check the connection timeout (FRONA_BROWSER_CONNECTION_TIMEOUT_MS, default: 30000)

Web search returning no results

• Verify SearXNG is running: docker compose ps searxng
• Check that FRONA_SEARCH_SEARXNG_BASE_URL is set (default: http://searxng:8080)
• Test SearXNG directly: curl http://localhost:8080/search?q=test&format=json
• SearXNG needs outbound internet access to query search engines

Authentication issues

”Invalid token” errors

• The encryption secret may have changed, invalidating existing tokens
• Access tokens expire after 15 minutes. The frontend should auto-refresh
• Check that the server clock is synchronized (JWT validation is time-sensitive)

Can’t log in after restart

• If you changed FRONA_AUTH_ENCRYPTION_SECRET, all tokens are invalidated
• Clear browser cookies and log in again

Database issues

”Database locked” or corruption

• Only one engine instance should access the database at a time
• If the engine was killed ungracefully, RocksDB may need recovery. Restart the container
• Check disk space. SurrealDB needs room for write-ahead logs

Data not persisting across restarts

• Make sure the data/ directory is mounted as a volume
• Check file permissions on the host directory

Performance issues

High memory usage

• Browserless is the most memory-intensive component (200-500 MB per session)
• Reduce MAX_CONCURRENT_SESSIONS in the Browserless config
• Check for orphaned browser sessions that weren’t properly closed

Slow responses

• Check your LLM provider’s API status
• Review the number of tool turns per response (FRONA_INFERENCE_MAX_TOOL_TURNS)
• Large context windows consume more tokens and take longer
• Check if compaction is running (it may temporarily increase load)

Sandbox issues

CLI commands failing on macOS

• Landlock sandboxing only works on Linux
• On macOS, sandboxing is limited. Set FRONA_SERVER_SANDBOX_DISABLED=true for development

”Permission denied” in CLI tool

• Check the sandbox configuration for the agent
• Verify that network_access is enabled if the command needs internet
• Check allowed_network_destinations if specific hosts are needed

Getting help

Check the logs first:

# All services
docker compose logs

# Specific service
docker compose logs frona --tail 100

# Follow logs in real-time
docker compose logs -f frona

If you’re still stuck, open an issue at github.com/fronalabs/frona with:

• Your Docker Compose configuration (redact secrets)
• Relevant log output
• Steps to reproduce the issue