Appearance

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

Services won't start ​

Container exits immediately ​

Check the logs for the specific service:

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

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

bash
# 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
Frona AI