What causes "服务不可用: {str(e)}" in datawhalechina/hello-agents?

Check backend/.env has a valid AMAP_API_KEY (that is the most common init failure)

datawhalechina/hello-agents · error · HTTPException

服务不可用: {str(e)}

Error message

服务不可用: {str(e)}

What it means

HTTPException(503) raised by GET /map/health when constructing/getting the Amap MCP service fails — i.e. the health probe itself cannot initialize the service it is supposed to check. Notably it dereferences service.mcp_tool._available_tools, so even a partially-initialized service (or one whose MCPTool exposes no _available_tools attribute in a newer version) fails here.

Source

Thrown at code/chapter13/helloagents-trip-planner/backend/app/api/routes/map.py:159

@router.get(
    "/health",
    summary="健康检查",
    description="检查地图服务是否正常"
)
async def health_check():
    """健康检查"""
    try:
        # 检查服务是否可用
        service = get_amap_service()
        
        return {
            "status": "healthy",
            "service": "map-service",
            "mcp_tools_count": len(service.mcp_tool._available_tools)
        }
    except Exception as e:
        raise HTTPException(
            status_code=503,
            detail=f"服务不可用: {str(e)}"
        )

View on GitHub (pinned to 606a07d341)

Solutions

Check backend/.env has a valid AMAP_API_KEY (that is the most common init failure)
Run `uvx amap-mcp-server` manually on the host to confirm it can start
Pin the MCP wrapper library version the project was written against — the health check reads the private _available_tools attribute
Treat any non-200 from /map/health as 'do not send traffic' in orchestration/monitoring

Example fix

# before
"mcp_tools_count": len(service.mcp_tool._available_tools)  # AttributeError on version change

# after
tools = getattr(getattr(service, 'mcp_tool', None), '_available_tools', []) or []
return {"status": "healthy", "service": "map-service", "mcp_tools_count": len(tools)}

Defensive patterns

Strategy: try-catch

Validate before calling

import requests

h = requests.get(f'{BASE}/map/health', timeout=5)
if h.status_code == 503:
    raise SystemExit(f'Map service down: {h.json().get("detail")}')

Try / catch

r = requests.get(f'{BASE}/map/health')
if r.status_code == 503:
    detail = r.json().get('detail', '')
    if 'AMAP_API_KEY' in detail:
        fix_env_and_restart()
    elif 'uvx' in detail or 'amap-mcp-server' in detail:
        install_uv_and_retry()

Prevention

Wire /map/health into readiness probes so bad config blocks rollout, not traffic
Pin versions of the MCP wrapper class — the check reads private attributes
Verify uvx availability in the container image at build time

When it happens

Trigger: get_amap_service() raising because AMAP_API_KEY is unset (ValueError from amap_service.py:25); amap-mcp-server failing to launch so MCPTool construction throws; MCPTool version change renaming/removing the private _available_tools attribute (AttributeError inside try).

Common situations: Deployment without .env; uvx unavailable in the container; library upgrade of the MCP wrapper class changing internals; first boot where subprocess startup times out.

Related errors

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