{"record":{"id":"35193dffefa17c4e","repo":"datawhalechina/hello-agents","slug":"recommend-unavailable","errorCode":"RECOMMEND_UNAVAILABLE","errorMessage":"推荐服务不可用: {e}","messagePattern":"推荐服务不可用: (.+?)","errorType":"http","errorClass":"AppError","httpStatus":503,"severity":"error","filePath":"Co-creation-projects/aatanxiao12-beep-YingQian/backend/app/api/routes/recommend.py","lineNumber":59,"sourceCode":"\n\n@router.get(\n    \"/health\",\n    summary=\"推荐服务健康检查\",\n    description=\"返回各 Agent 名称与工具数量；初始化失败时 503。\",\n)\nasync def recommend_health():\n    try:\n        agent = get_movie_recommender()\n        snap = agent.health_snapshot()\n        return {\n            \"status\": \"healthy\",\n            \"service\": \"recommend\",\n            **snap,\n        }\n    except Exception as e:\n        logger.exception(\"recommend health 失败\")\n        raise AppError(\n            f\"推荐服务不可用: {e}\",\n            code=\"RECOMMEND_UNAVAILABLE\",\n            status_code=503,\n        ) from e\n","sourceCodeStart":41,"sourceCodeEnd":64,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/aatanxiao12-beep-YingQian/backend/app/api/routes/recommend.py#L41-L64","documentation":"AppError with code RECOMMEND_UNAVAILABLE (HTTP 503) raised by the /recommend/health endpoint when constructing the recommender agent or taking its health snapshot throws. get_movie_recommender builds a multi-agent pipeline (profile agent, retrieval agent with TMDB tool, recommendation agent), so failure typically means missing LLM credentials, TMDB configuration, or an error constructing an upstream client. The original exception is logged via logger.exception and chained.","triggerScenarios":"GET /recommend/health when the process env lacks the LLM API key (e.g. OPENAI_API_KEY / DASHSCOPE_API_KEY depending on config); TMDB tool constructor raising MovieServiceError because TMDB_ACCESS_TOKEN/TMDB_API_KEY are unset; agent module import or wiring error (bad prompt file path, schema mismatch); singleton cached in a failed half-initialized state.","commonSituations":"Deploying the backend without copying .env; rotating/revoked API keys after the service was healthy; health check hitting a fresh worker that has different env; local run pointing at a pydantic-settings config missing required fields.","solutions":["Check backend logs for the 'recommend health 失败' stack trace — it names the actual constructor failure","Ensure required env vars (LLM key and TMDB_ACCESS_TOKEN or TMDB_API_KEY) are set in the deployment environment, not just locally","Restart the worker after fixing env so the cached singleton is rebuilt","If get_movie_recommender memoizes failures, clear/reset the cached instance on config reload","Point monitoring at this 503 as the deployment gate before routing traffic"],"exampleFix":"// before (ops): curl /recommend/health blindly\n// after: check 503 body code and consult logs\n# response body on failure:\n# {\"code\": \"RECOMMEND_UNAVAILABLE\", \"message\": \"推荐服务不可用: <cause>\"}\n# then inspect: docker logs <backend> | grep 'recommend health 失败' -A 20\n# and fix the named missing credential in the environment before re-checking","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"# caller of the API (frontend/monitoring):\nresp = await client.get('/recommend/health')\nif resp.status_code == 503:\n    body = resp.json()\n    if body.get('code') == 'RECOMMEND_UNAVAILABLE':\n        alert_onboarding('recommender down: ' + body.get('message', ''))","preventionTips":["Wire /recommend/health into deployment gates so a misconfigured agent never receives traffic","Validate required credentials at process startup (lifespan) rather than per-request","Keep .env.template listing every key the agent chain needs (LLM + TMDB) so omissions are visible"],"tags":["fastapi","health-check","configuration","http-503","movie-recommender"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}