{"record":{"id":"12d366f9d5a7c3b9","repo":"datawhalechina/hello-agents","slug":"research-failed-12d366","errorCode":null,"errorMessage":"Research failed","messagePattern":"Research failed","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"Co-creation-projects/huailishang-AgentPlatformBase/agents/deep_research/src/main.py","lineNumber":127,"sourceCode":"            config.use_tool_calling,\n            config.strip_thinking_tokens,\n            _mask_secret(config.llm_api_key),\n        )\n\n    @app.get(\"/healthz\")\n    def health_check() -> Dict[str, str]:\n        return {\"status\": \"ok\"}\n\n    @app.post(\"/research\", response_model=ResearchResponse)\n    def run_research(payload: ResearchRequest) -> ResearchResponse:\n        try:\n            config = _build_config(payload)\n            agent = DeepResearchAgent(config=config)\n            result = agent.run(payload.topic)\n        except ValueError as exc:  # Likely due to unsupported configuration\n            raise HTTPException(status_code=400, detail=str(exc)) from exc\n        except Exception as exc:  # pragma: no cover - defensive guardrail\n            raise HTTPException(status_code=500, detail=\"Research failed\") from exc\n\n        todo_payload = [\n            {\n                \"id\": item.id,\n                \"title\": item.title,\n                \"intent\": item.intent,\n                \"query\": item.query,\n                \"status\": item.status,\n                \"summary\": item.summary,\n                \"sources_summary\": item.sources_summary,\n                \"note_id\": item.note_id,\n                \"note_path\": item.note_path,\n            }\n            for item in result.todo_items\n        ]\n\n        return ResearchResponse(\n            report_markdown=(result.report_markdown or result.running_summary or \"\"),","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/huailishang-AgentPlatformBase/agents/deep_research/src/main.py#L109-L145","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nexcept Exception as exc:  # pragma: no cover\n    raise HTTPException(status_code=500, detail=\"Research failed\") from exc\n\n# after (keep detail opaque to client but log the cause)\nexcept Exception as exc:\n    logger.exception(\"research run failed\", extra={\"topic\": payload.topic})\n    raise HTTPException(status_code=500, detail=\"Research failed\") from exc","handlingStrategy":"retry","validationCode":"# Client-side preflight: cheap health check before a long research call\nimport requests\nif requests.get(f\"{BASE}/health\", timeout=5).json().get(\"status\") != \"ok\":\n    raise SystemExit(\"deep_research service unhealthy\")","typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    try:\n        resp = requests.post(f\"{BASE}/research\", json=payload, timeout=600)\n        if resp.status_code == 500:\n            raise RuntimeError(\"server error\")\n        break\n    except RuntimeError:\n        if attempt == 2:\n            raise\n        time.sleep(2 ** attempt)","preventionTips":["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."],"tags":["http-500","fastapi","error-handling","python"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}