From 6b5c4fe6dd11f8032aa7f92aa497d5ae09548ffa Mon Sep 17 00:00:00 2001
From: Willem Jiang <willem.jiang@gmail.com>
Date: Sun, 8 Mar 2026 21:06:57 +0800
Subject: [PATCH] fix(dev): improve gateway startup diagnostics for config
 errors (#1020)

---
 Makefile                   | 19 ++++++++++++++++++-
 README.md                  |  4 ++++
 backend/CLAUDE.md          |  2 +-
 backend/src/gateway/app.py |  6 +++---
 4 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/Makefile b/Makefile
index b9cf33e..43516ef 100644
--- a/Makefile
+++ b/Makefile
@@ -170,6 +170,20 @@ dev:
 	@echo "  → Frontend: Next.js"
 	@echo "  → Nginx: Reverse Proxy"
 	@echo ""
+	@if ! { \
+			[ -n "$$DEER_FLOW_CONFIG_PATH" ] && [ -f "$$DEER_FLOW_CONFIG_PATH" ] || \
+			[ -f backend/config.yaml ] || \
+			[ -f config.yaml ]; \
+		}; then \
+		echo "✗ No DeerFlow config file found."; \
+		echo "  Checked these locations:"; \
+		echo "    - $$DEER_FLOW_CONFIG_PATH (when DEER_FLOW_CONFIG_PATH is set)"; \
+		echo "    - backend/config.yaml"; \
+		echo "    - ./config.yaml"; \
+		echo ""; \
+		echo "  Run 'make config' from the repo root to generate ./config.yaml, then set required model API keys in .env or your config file."; \
+		exit 1; \
+	fi
 	@cleanup() { \
 		trap - INT TERM; \
 		echo ""; \
@@ -196,7 +210,10 @@ dev:
 	sleep 3; \
 	if ! lsof -i :8001 -sTCP:LISTEN -t >/dev/null 2>&1; then \
 		echo "✗ Gateway API failed to start. Last log output:"; \
-		tail -30 logs/gateway.log; \
+		tail -60 logs/gateway.log; \
+		echo ""; \
+		echo "Likely configuration errors:"; \
+		grep -E "Failed to load configuration|Environment variable .* not found|config\.yaml.*not found" logs/gateway.log | tail -5 || true; \
 		cleanup; \
 	fi; \
 	echo "✓ Gateway API started on localhost:8001"; \
diff --git a/README.md b/README.md
index 21c812e..9dca2a2 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,7 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
 
 - [🦌 DeerFlow - 2.0](#-deerflow---20)
   - [Official Website](#official-website)
+  - [InfoQuest](#infoquest)
   - [Table of Contents](#table-of-contents)
   - [Quick Start](#quick-start)
     - [Configuration](#configuration)
@@ -50,6 +51,7 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
     - [Context Engineering](#context-engineering)
     - [Long-Term Memory](#long-term-memory)
   - [Recommended Models](#recommended-models)
+  - [Embedded Python Client](#embedded-python-client)
   - [Documentation](#documentation)
   - [Contributing](#contributing)
   - [License](#license)
@@ -144,6 +146,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
 
 If you prefer running services locally:
 
+Prerequisite: complete the "Configuration" steps above first (`make config` and model API keys). `make dev` requires a valid configuration file (defaults to `config.yaml` in the project root; can be overridden via `DEER_FLOW_CONFIG_PATH`).
+
 1. **Check prerequisites**:
    ```bash
    make check  # Verifies Node.js 22+, pnpm, uv, nginx
diff --git a/backend/CLAUDE.md b/backend/CLAUDE.md
index 5bf9917..75df741 100644
--- a/backend/CLAUDE.md
+++ b/backend/CLAUDE.md
@@ -74,7 +74,7 @@ When making code changes, you MUST update the relevant documentation:
 ```bash
 make check      # Check system requirements
 make install    # Install all dependencies (frontend + backend)
-make dev        # Start all services (LangGraph + Gateway + Frontend + Nginx)
+make dev        # Start all services (LangGraph + Gateway + Frontend + Nginx), with config.yaml preflight
 make stop       # Stop all services
 ```
 
diff --git a/backend/src/gateway/app.py b/backend/src/gateway/app.py
index cddc23d..edcf6ad 100644
--- a/backend/src/gateway/app.py
+++ b/backend/src/gateway/app.py
@@ -1,5 +1,4 @@
 import logging
-import sys
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
@@ -38,8 +37,9 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         get_app_config()
         logger.info("Configuration loaded successfully")
     except Exception as e:
-        logger.error(f"Failed to load configuration: {e}")
-        sys.exit(1)
+        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}")