datawhalechina/hello-agents · error · HTTPException

路线规划失败: {str(e)}

Error message

路线规划失败: {str(e)}

What it means

HTTPException(500) raised by POST /map/route in the chapter13 backend when service.plan_route(...) (route planning via the Amap MCP tools) throws. The route involves origin/destination coordinates or names plus a route_type, and any failure in the MCP tool chain or upstream Amap API becomes this 500.

Source

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

        
        # 规划路线
        route_info = service.plan_route(
            origin_address=request.origin_address,
            destination_address=request.destination_address,
            origin_city=request.origin_city,
            destination_city=request.destination_city,
            route_type=request.route_type
        )
        
        return RouteResponse(
            success=True,
            message="路线规划成功",
            data=route_info
        )
        
    except Exception as e:
        print(f"❌ 路线规划失败: {str(e)}")
        raise HTTPException(
            status_code=500,
            detail=f"路线规划失败: {str(e)}"
        )


@router.get(
    "/health",
    summary="健康检查",
    description="检查地图服务是否正常"
)
async def health_check():
    """健康检查"""
    try:
        # 检查服务是否可用
        service = get_amap_service()
        
        return {
            "status": "healthy",

View on GitHub (pinned to 606a07d341)

Solutions

  1. Read the '❌ 路线规划失败' log line and embedded detail for the root cause
  2. Test with simple, well-known city names (e.g. 北京 -> 上海) to rule out geocoding of obscure inputs
  3. Confirm AMAP_API_KEY works and the direction API is enabled for it
  4. Check /map/health before calling to detect service-init failures early

Example fix

# before
body = {'origin': '我家附近', 'destination': '那个商场'}  # unresolvable -> 500

# after
body = {'origin_city': '北京', 'destination_city': '上海', 'route_type': 'driving'}
r = requests.post(f'{BASE}/map/route', json=body)
r.raise_for_status()
Defensive patterns

Strategy: validation

Validate before calling

def valid_route_request(body: dict) -> bool:
    return (
        bool(str(body.get('origin_city', '')).strip())
        and bool(str(body.get('destination_city', '')).strip())
        and body.get('route_type') in {'driving', 'transit', 'walking', 'cycling'}
    )

Type guard

def is_supported_route_type(t: str) -> bool:
    return t in {'driving', 'transit', 'walking', 'cycling'}

Try / catch

try:
    r = requests.post(f'{BASE}/map/route', json=body, timeout=30)
    r.raise_for_status()
except requests.HTTPError as e:
    detail = e.response.json().get('detail', '')
    if 'geocode' in detail.lower() or '无效' in detail:
        body['origin_city'], body['destination_city'] = '北京', '上海'  # simplified retry
    raise

Prevention

When it happens

Trigger: Origin/destination strings the geocoding sub-tools cannot resolve; missing AMAP_API_KEY; amap-mcp-server subprocess not running; malformed request fields (empty origin_city/destination_city) reaching the service.

Common situations: Users passing landmark names that geocode to nothing; env not configured after redeploy; upstream Amap direction API quota or coordinate-system (GPS vs GCJ-02) errors.

Related errors

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