bytedance/deer-flow · critical · SystemExit

GATEWAY_WORKERS={workers} cannot enable agentic browser tool

Error message

GATEWAY_WORKERS={workers} cannot enable agentic browser tools: browser sessions are process-local and uvicorn does not provide thread affinity. Set GATEWAY_WORKERS=1 or disable the browser_navigate tool.

What it means

SystemExit raised at startup when GATEWAY_WORKERS>1 and browser tools are enabled in config: browser sessions are process-local and uvicorn gives no thread/worker affinity, so a browser_navigate session created on worker A cannot be driven by a request routed to worker B. The gate (via browser_multi_worker_error) fails fast instead of letting sessions break non-deterministically under the load balancer.

Source

Thrown at backend/app/gateway/deps.py:109

    backend = getattr(config.database, "backend", None)
    run_events_backend = getattr(getattr(config, "run_events", None), "backend", None)
    run_ownership = getattr(config, "run_ownership", None)

    if multi_instance_requested and backend != "postgres":
        raise SystemExit(f"scheduler.multi_instance=true requires database.backend='postgres'. database.backend is '{backend}'. Set scheduler.multi_instance=false or configure Postgres.")
    if multi_instance_requested and run_events_backend != "db":
        raise SystemExit(f"scheduler.multi_instance=true requires run_events.backend='db'. run_events.backend is '{run_events_backend}'. Set scheduler.multi_instance=false or configure run_events.backend: db.")
    if multi_instance_requested and (run_ownership is None or not run_ownership.heartbeat_enabled):
        raise SystemExit("scheduler.multi_instance=true requires run_ownership.heartbeat_enabled=true so peer runs retain a valid lease. Set scheduler.multi_instance=false or enable run ownership heartbeats.")

    if workers <= 1:
        return

    if config.scheduler.enabled and not multi_instance_scheduler:
        raise SystemExit(f"GATEWAY_WORKERS={workers} cannot run with scheduler.enabled=true because each worker starts its own scheduler. Set GATEWAY_WORKERS=1, scheduler.multi_instance=true, or scheduler.enabled=false.")

    if _browser_tools_enabled_in_config(config):
        raise SystemExit(browser_multi_worker_error(workers))

    if backend != "postgres":
        raise SystemExit(f"GATEWAY_WORKERS={workers} requires database.backend='postgres', but database.backend is '{backend}'. SQLite cannot support concurrent multi-process access. Set GATEWAY_WORKERS=1 or switch to Postgres.")

    if run_events_backend != "db":
        raise SystemExit(
            f"GATEWAY_WORKERS={workers} requires run_events.backend='db', but run_events.backend is '{run_events_backend}'. "
            "Memory and JSONL event stores are process-local, so delivery receipt singleton guarantees cannot hold across workers. "
            "Set GATEWAY_WORKERS=1 or configure run_events.backend: db."
        )

    if run_ownership is None or not run_ownership.heartbeat_enabled:
        raise SystemExit(
            f"GATEWAY_WORKERS={workers} requires run_ownership.heartbeat_enabled=true. "
            "Without heartbeat, every run has a NULL lease, so reconciliation "
            "treats all inflight runs as orphans — Worker B would kill Worker A's "
            "live runs on every rolling update or scale-up. "
            "Set run_ownership.heartbeat_enabled=true in config.yaml."

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Set GATEWAY_WORKERS=1
2. Or disable the browser_navigate tool in config.yaml
3. If browser automation at scale is needed, run it in a separate single-worker deployment

Example fix

# environment
# before
GATEWAY_WORKERS=4
# after
GATEWAY_WORKERS=1

workers = int(os.environ.get("GATEWAY_WORKERS", "1"))
assert not (workers > 1 and browser_tools_enabled(load_config())), "browser tools require GATEWAY_WORKERS=1"

When it happens

Trigger: GATEWAY_WORKERS>1 with the browser_navigate tool / browser tools enabled in config.yaml (detected by _browser_tools_enabled_in_config).

Common situations: Scaling out workers for capacity on a deployment that demos browser automation; enabling browser tools on an existing multi-worker production config; container images with a high default GATEWAY_WORKERS.

Related errors

• GATEWAY_WORKERS={workers} cannot run with scheduler.enabled=
• GATEWAY_WORKERS={workers} requires database.backend='postgre
• GATEWAY_WORKERS={workers} requires run_events.backend='db',
• GATEWAY_WORKERS={workers} requires run_ownership.heartbeat_e
• scheduler.multi_instance=true requires database.backend='pos

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/30ad89c7b1dfa8a3. Report an issue: GitHub.