datawhalechina/hello-agents · error · HTTPException
Research failed
Error message
Research failed
What it means
A catch-all HTTP 500 from the deep-research FastAPI service: any exception raised while building the agent config or running the research that is not a ValueError (ValueErrors become 400) is masked as "Research failed". The original exception is chained via `from exc` in the server logs but hidden from the client, so the response text alone gives no diagnosis.
Source
Thrown at Co-creation-projects/huailishang-AgentPlatformBase/agents/deep_research/src/main.py:127
config.use_tool_calling,
config.strip_thinking_tokens,
_mask_secret(config.llm_api_key),
)
@app.get("/healthz")
def health_check() -> Dict[str, str]:
return {"status": "ok"}
@app.post("/research", response_model=ResearchResponse)
def run_research(payload: ResearchRequest) -> ResearchResponse:
try:
config = _build_config(payload)
agent = DeepResearchAgent(config=config)
result = agent.run(payload.topic)
except ValueError as exc: # Likely due to unsupported configuration
raise HTTPException(status_code=400, detail=str(exc)) from exc
except Exception as exc: # pragma: no cover - defensive guardrail
raise HTTPException(status_code=500, detail="Research failed") from exc
todo_payload = [
{
"id": item.id,
"title": item.title,
"intent": item.intent,
"query": item.query,
"status": item.status,
"summary": item.summary,
"sources_summary": item.sources_summary,
"note_id": item.note_id,
"note_path": item.note_path,
}
for item in result.todo_items
]
return ResearchResponse(
report_markdown=(result.report_markdown or result.running_summary or ""),View on GitHub (pinned to 606a07d341)
Solutions
- Check the service's server-side logs/traceback — the chained `from exc` preserves the root cause there.
- Verify LLM/search provider credentials and connectivity from the service host (curl the provider, check env vars).
- Retry the request — transient upstream network or provider failures often clear.
- If the error is deterministic, reproduce locally by instantiating DeepResearchAgent(config) and calling run(topic) outside FastAPI to get the full traceback.
- For better operability, log exc details server-side and include a correlation id in the 500 detail.
Example fix
# before
except Exception as exc: # pragma: no cover
raise HTTPException(status_code=500, detail="Research failed") from exc
# after (keep detail opaque to client but log the cause)
except Exception as exc:
logger.exception("research run failed", extra={"topic": payload.topic})
raise HTTPException(status_code=500, detail="Research failed") from exc Defensive patterns
Strategy: retry
Validate before calling
# Client-side preflight: cheap health check before a long research call
import requests
if requests.get(f"{BASE}/health", timeout=5).json().get("status") != "ok":
raise SystemExit("deep_research service unhealthy") Try / catch
for attempt in range(3):
try:
resp = requests.post(f"{BASE}/research", json=payload, timeout=600)
if resp.status_code == 500:
raise RuntimeError("server error")
break
except RuntimeError:
if attempt == 2:
raise
time.sleep(2 ** attempt) Prevention
- Check server logs for the chained root-cause traceback before changing client code.
- Alert on 500 rate from /research to catch provider/auth degradation early.
- Log correlation ids with each request so 500s map to tracebacks quickly.
When it happens
Trigger: POST /research with a valid-shaped payload where agent.run() raises unexpectedly: network failure fetching sources, LLM provider auth/timeout errors, parsing bugs, or missing credentials. Only config-shaped ValueErrors surface as 400; everything else becomes this 500.
Common situations: Missing or expired LLM API keys on the server; upstream search/API providers rate-limiting or timing out during a long research run; transient network issues; unhandled edge cases in note generation.
Related errors
AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14).
Data as JSON: /api/errors/12d366f9d5a7c3b9.
Report an issue: GitHub.