datawhalechina/hello-agents · error · HTTPException

POI搜索失败: {str(e)}

Error message

POI搜索失败: {str(e)}

What it means

HTTPException(500) raised by the FastAPI route GET /map/poi/search (chapter13 trip planner backend) when service.search_poi(...) throws. The route is a thin wrapper: any failure inside the Amap MCP service — subprocess startup, API key, network, or tool invocation — is converted into this 500 with the original message embedded.

Source

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

    Returns:
        POI搜索结果
    """
    try:
        # 获取服务实例
        service = get_amap_service()
        
        # 搜索POI
        pois = service.search_poi(keywords, city, citylimit)
        
        return POISearchResponse(
            success=True,
            message="POI搜索成功",
            data=pois
        )
        
    except Exception as e:
        print(f"❌ POI搜索失败: {str(e)}")
        raise HTTPException(
            status_code=500,
            detail=f"POI搜索失败: {str(e)}"
        )


@router.get(
    "/weather",
    response_model=WeatherResponse,
    summary="查询天气",
    description="查询指定城市的天气信息"
)
async def get_weather(
    city: str = Query(..., description="城市名称", example="北京")
):
    """
    查询天气
    
    Args:

View on GitHub (pinned to 606a07d341)

Solutions

  1. Read the printed '❌ POI搜索失败' server log line and the embedded {str(e)} — it names the real cause
  2. Confirm AMAP_API_KEY is set in backend/.env and valid (test it against https://restapi.amap.com/v3/place/text directly)
  3. Verify `uvx amap-mcp-server` runs on the server host (uv installed, network available)
  4. Hit GET /map/health first to confirm the map service initialized before searching

Example fix

# before
resp = requests.get(f'{BASE}/map/poi/search', params={'keywords': '故宫'})
resp.raise_for_status()

# after
health = requests.get(f'{BASE}/map/health')
if health.status_code != 200:
    raise SystemExit('Map service unhealthy: ' + health.text)
resp = requests.get(f'{BASE}/map/poi/search', params={'keywords': '故宫'})
resp.raise_for_status()
Defensive patterns

Strategy: try-catch

Validate before calling

import requests

if requests.get(f'{BASE}/map/health').status_code != 200:
    raise SystemExit('Map service unhealthy; check AMAP_API_KEY and uvx')

Try / catch

try:
    resp = requests.get(f'{BASE}/map/poi/search', params={'keywords': kw, 'city': city}, timeout=15)
    resp.raise_for_status()
except requests.HTTPError as e:
    detail = e.response.json().get('detail', '')
    log.warning('POI search failed: %s', detail)  # detail carries the root cause

Prevention

When it happens

Trigger: AMAP_API_KEY missing/invalid so the amap-mcp-server tool call fails; the uvx amap-mcp-server subprocess cannot start (uvx not installed, offline machine); network failure reaching restapi.amap.com; empty keywords argument causing the underlying API to error.

Common situations: Fresh clone without .env configured; server deployed without uv/uvx on PATH; Amap API quota exhausted or key domain-restricted; cold start timing where the MCP tool list is not yet expanded.

Related errors

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