datawhalechina/hello-agents · error · HTTPException

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

Error message

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

What it means

HTTPException(500) raised by GET /poi/search (chapter13 poi routes) when amap_service.search_poi(keywords, city) throws. Identical failure surface to the /map/poi/search route (both call the Amap service) but on the dedicated poi router; the cause message is preserved in detail.

Source

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

        keywords: 搜索关键词
        city: 城市名称

    Returns:
        搜索结果
    """
    try:
        amap_service = get_amap_service()
        result = amap_service.search_poi(keywords, city)

        return {
            "success": True,
            "message": "搜索成功",
            "data": result
        }

    except Exception as e:
        print(f"❌ 搜索POI失败: {str(e)}")
        raise HTTPException(
            status_code=500,
            detail=f"搜索POI失败: {str(e)}"
        )


@router.get(
    "/photo",
    summary="获取景点图片",
    description="根据景点名称从Unsplash获取图片"
)
async def get_attraction_photo(name: str):
    """
    获取景点图片

    Args:
        name: 景点名称

    Returns:

View on GitHub (pinned to 606a07d341)

Solutions

  1. Read the '❌ 搜索POI失败' log and embedded detail for the true cause
  2. Validate AMAP_API_KEY in .env and test the Amap place/text API directly
  3. Confirm uvx + network availability on the host/container
  4. Default city='北京' applies if omitted — pass an explicit supported city to avoid upstream errors

Example fix

# before
r = requests.get(f'{BASE}/poi/search', params={'keywords': ''})  # empty -> 500

# after
assert keywords.strip(), 'keywords required'
r = requests.get(f'{BASE}/poi/search', params={'keywords': keywords, 'city': city})
r.raise_for_status()
Defensive patterns

Strategy: try-catch

Validate before calling

assert keywords and keywords.strip(), 'keywords must be non-empty'
assert city.strip(), 'city must be non-empty'
# service-level precheck
import requests
assert requests.get(f'{BASE}/map/health').status_code == 200, 'map service down'

Try / catch

try:
    r = requests.get(f'{BASE}/poi/search', params={'keywords': kw, 'city': city}, timeout=15)
    r.raise_for_status()
except requests.HTTPError as e:
    detail = e.response.json().get('detail', '')
    if 'KEY' in detail.upper():
        raise SystemExit('Amap key problem — fix backend .env')
    raise

Prevention

When it happens

Trigger: Missing/invalid AMAP_API_KEY; amap-mcp-server subprocess not startable on the host; empty keywords param; network egress blocked from the backend container.

Common situations: Env var not loaded in the deployed environment; uvx missing in Docker image; Amap quota exhausted; calling before service initialization completed.

Related errors

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