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

Provider and model issues ​

A connection validates, but the model fails ​

Validation checks the connection's authentication or connectivity. It does not guarantee model access or remaining quota. Expand Details on the failed chat response and check its category, provider, model, and HTTP status.

  • For an authentication error, check the active credential source in Administration → Providers, then update the key or sign in again.
  • For a permission or unavailable-model error, verify that the account can use the exact model ID. Azure requires a deployment name; a base-model ID is not enough.
  • For a rate limit, check the provider's quota and the group's fallback settings.
  • If model discovery fails, enter a model ID manually. A catalogue entry alone does not establish access.

A proxy fails after upgrading ​

OpenAI-branded connections now default to Responses. For a Chat Completions-only endpoint, set api: completions on the model group and its relevant fallbacks, save, and restart. See protocol selection.

Environment credentials are missing ​

Make sure the named variable is forwarded into the Frona container. The UI's environment-variable selector lists server-side names, not values. Arbitrary variable names must be referenced explicitly by a connection; they are not automatically discovered.

Settings will not save or do not take effect ​

If Frona reports a configuration revision conflict, reload settings to pick up the latest file before editing again. New connection details need validation before saving. Follow the restart banner to activate saved configuration; credential logout takes effect for subsequent use immediately.

Malformed YAML or an unreadable config file now stops startup with an error. Correct the file identified by FRONA_CONFIG before restarting.

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