bytedance/deer-flow · critical · RuntimeError

Failed to load configuration during gateway startup: {e}

Error message

Failed to load configuration during gateway startup: {e}

What it means

During FastAPI startup (lifespan), the Gateway loads the app config, configures logging, ensures the browser runtime, and checks auth posture. Any exception in that chain is wrapped into this RuntimeError with the original message, logged with a full traceback, and re-raised — which aborts Gateway startup entirely. The {e} content is the real diagnosis; this wrapper marks the phase where it failed.

Source

Thrown at backend/app/gateway/app.py:209

    """Application lifespan handler."""

    # Load config and check necessary environment variables at startup.
    # `startup_config` is a local snapshot used only for one-shot bootstrap
    # work (logging level, langgraph_runtime engines, channels). Request-time
    # config resolution always routes through `get_app_config()` in
    # `app/gateway/deps.py::get_config()` so `config.yaml` edits become
    # visible without a process restart. We deliberately do NOT cache this
    # snapshot on `app.state` to keep that contract enforceable.
    try:
        startup_config = get_app_config()
        configure_logging(startup_config)
        ensure_browser_runtime_available(startup_config)
        logger.info("Configuration loaded successfully")
        warn_if_auth_disabled_enabled()
    except Exception as e:
        error_msg = f"Failed to load configuration during gateway startup: {e}"
        logger.exception(error_msg)
        raise RuntimeError(error_msg) from e
    config = get_gateway_config()
    logger.info(f"Starting API Gateway on {config.host}:{config.port}")

    from deerflow.skills.projection import ensure_public_skill_projection

    public_projection_ready = await asyncio.to_thread(ensure_public_skill_projection, app_config=startup_config)
    if public_projection_ready:
        logger.info("Ensured the public skill projection; user projections repair lazily on sandbox acquire")

    # Agent observability (Monocle). Off by default; enabled with
    # MONOCLE_TRACING. Initialized here at startup — not at import time — so a
    # plain `import deerflow.agents` never installs a process-global tracer.
    # Unlike LangSmith/Langfuse, whose validation failures abort the agent run,
    # a bad Monocle config only logs: the Gateway keeps serving without tracing.
    try:
        setup_monocle_tracing_if_enabled()
    except Exception:  # observability must never break startup
        logger.exception("Monocle tracing setup failed; continuing without it")

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Read the logged traceback just below this message — it names the exact config key or runtime check that failed.
2. Run `make doctor` and `make config` to validate/regenerate config.yaml.
3. If the browser runtime is the cause, install it or disable the browser feature in config.yaml.
4. Restart the Gateway after the fix; startup will not retry automatically.

Example fix

# before: forgot to create config
# Gateway exits: Failed to load configuration during gateway startup: ...
mkdir -p config  # (wrong)

# after
cp config.example.yaml config.yaml
cp extensions_config.example.json extensions_config.json
make dev

import yaml

def config_loads(path='config.yaml') -> bool:
    try:
        with open(path) as f:
            yaml.safe_load(f)
        return True
    except Exception:
        return False

if not config_loads():
    sys.exit('fix config.yaml before starting the gateway')

# in the process supervisor / container entrypoint
try:
    run_gateway()
except RuntimeError as e:
    if 'gateway startup' in str(e):
        print(e, file=sys.stderr)
        sys.exit(1)  # fail fast; supervisor backoff handles restarts
    raise

When it happens

Trigger: config.yaml missing required sections, failing schema validation, or referencing unreadable files; ensure_browser_runtime_available failing because Playwright/chromium is not installed; invalid logging config keys. Raised inside the startup hook, so the process exits instead of serving.

Common situations: First boot without running `make config`; config.yaml edited with syntax errors; upgrading DeerFlow where the config schema changed; running in an environment without the browser runtime the config requests; DEER_FLOW_HOME pointing at an unreadable path.

Related errors

• scheduler.multi_instance=true requires database.backend='pos
• scheduler.multi_instance=true requires run_events.backend='d
• scheduler.multi_instance=true requires run_ownership.heartbe
• GATEWAY_WORKERS={workers} cannot run with scheduler.enabled=
• GATEWAY_WORKERS={workers} cannot enable agentic browser tool

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