{"record":{"id":"8ebce564081a4421","repo":"bytedance/deer-flow","slug":"failed-to-load-configuration-during-gateway-startu","errorCode":null,"errorMessage":"Failed to load configuration during gateway startup: {e}","messagePattern":"Failed to load configuration during gateway startup: (.+?)","errorType":"console","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"backend/app/gateway/app.py","lineNumber":209,"sourceCode":"    \"\"\"Application lifespan handler.\"\"\"\n\n    # Load config and check necessary environment variables at startup.\n    # `startup_config` is a local snapshot used only for one-shot bootstrap\n    # work (logging level, langgraph_runtime engines, channels). Request-time\n    # config resolution always routes through `get_app_config()` in\n    # `app/gateway/deps.py::get_config()` so `config.yaml` edits become\n    # visible without a process restart. We deliberately do NOT cache this\n    # snapshot on `app.state` to keep that contract enforceable.\n    try:\n        startup_config = get_app_config()\n        configure_logging(startup_config)\n        ensure_browser_runtime_available(startup_config)\n        logger.info(\"Configuration loaded successfully\")\n        warn_if_auth_disabled_enabled()\n    except Exception as e:\n        error_msg = f\"Failed to load configuration during gateway startup: {e}\"\n        logger.exception(error_msg)\n        raise RuntimeError(error_msg) from e\n    config = get_gateway_config()\n    logger.info(f\"Starting API Gateway on {config.host}:{config.port}\")\n\n    from deerflow.skills.projection import ensure_public_skill_projection\n\n    public_projection_ready = await asyncio.to_thread(ensure_public_skill_projection, app_config=startup_config)\n    if public_projection_ready:\n        logger.info(\"Ensured the public skill projection; user projections repair lazily on sandbox acquire\")\n\n    # Agent observability (Monocle). Off by default; enabled with\n    # MONOCLE_TRACING. Initialized here at startup — not at import time — so a\n    # plain `import deerflow.agents` never installs a process-global tracer.\n    # Unlike LangSmith/Langfuse, whose validation failures abort the agent run,\n    # a bad Monocle config only logs: the Gateway keeps serving without tracing.\n    try:\n        setup_monocle_tracing_if_enabled()\n    except Exception:  # observability must never break startup\n        logger.exception(\"Monocle tracing setup failed; continuing without it\")","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/app.py#L191-L227","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the logged traceback just below this message — it names the exact config key or runtime check that failed.","Run `make doctor` and `make config` to validate/regenerate config.yaml.","If the browser runtime is the cause, install it or disable the browser feature in config.yaml.","Restart the Gateway after the fix; startup will not retry automatically."],"exampleFix":"# before: forgot to create config\n# Gateway exits: Failed to load configuration during gateway startup: ...\nmkdir -p config  # (wrong)\n\n# after\ncp config.example.yaml config.yaml\ncp extensions_config.example.json extensions_config.json\nmake dev","handlingStrategy":"try-catch","validationCode":"import yaml\n\ndef config_loads(path='config.yaml') -> bool:\n    try:\n        with open(path) as f:\n            yaml.safe_load(f)\n        return True\n    except Exception:\n        return False\n\nif not config_loads():\n    sys.exit('fix config.yaml before starting the gateway')","typeGuard":null,"tryCatchPattern":"# in the process supervisor / container entrypoint\ntry:\n    run_gateway()\nexcept RuntimeError as e:\n    if 'gateway startup' in str(e):\n        print(e, file=sys.stderr)\n        sys.exit(1)  # fail fast; supervisor backoff handles restarts\n    raise","preventionTips":["Gate deploys on `make doctor` + config validation in CI.","Keep config.yaml in config management with schema checks rather than ad-hoc edits.","Never ignore this exit — serving without config would be worse than not starting."],"tags":["gateway","config","startup","critical"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}