What causes "推荐服务不可用: {e}" in datawhalechina/hello-agents?

Check backend logs for the 'recommend health 失败' stack trace — it names the actual constructor failure

datawhalechina/hello-agents · error · AppError

RECOMMEND_UNAVAILABLE

RECOMMEND_UNAVAILABLE

Error message

推荐服务不可用: {e}

What it means

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.

Source

Thrown at Co-creation-projects/aatanxiao12-beep-YingQian/backend/app/api/routes/recommend.py:59


@router.get(
    "/health",
    summary="推荐服务健康检查",
    description="返回各 Agent 名称与工具数量；初始化失败时 503。",
)
async def recommend_health():
    try:
        agent = get_movie_recommender()
        snap = agent.health_snapshot()
        return {
            "status": "healthy",
            "service": "recommend",
            **snap,
        }
    except Exception as e:
        logger.exception("recommend health 失败")
        raise AppError(
            f"推荐服务不可用: {e}",
            code="RECOMMEND_UNAVAILABLE",
            status_code=503,
        ) from e

View on GitHub (pinned to 606a07d341)

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

Example fix

// before (ops): curl /recommend/health blindly
// after: check 503 body code and consult logs
# response body on failure:
# {"code": "RECOMMEND_UNAVAILABLE", "message": "推荐服务不可用: <cause>"}
# then inspect: docker logs <backend> | grep 'recommend health 失败' -A 20
# and fix the named missing credential in the environment before re-checking

Defensive patterns

Strategy: try-catch

Try / catch

# caller of the API (frontend/monitoring):
resp = await client.get('/recommend/health')
if resp.status_code == 503:
    body = resp.json()
    if body.get('code') == 'RECOMMEND_UNAVAILABLE':
        alert_onboarding('recommender down: ' + body.get('message', ''))

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/35193dffefa17c4e. Report an issue: GitHub.