Fix: Add error handling for missing 'tiles' key in stac_tile response

[giswqs]

Description

The NAIP imagery notebook was failing with KeyError: 'tiles' when trying to visualize search results. This was caused by two issues:

1. Root cause: When stac_stats fails for Planetary Computer items, it was overwriting the titiler_endpoint variable with a fallback string endpoint. This caused the subsequent tile request to use the wrong endpoint path (/stac/ instead of /item/), which expects a url parameter instead of collection+item parameters.

2. Symptom: When the wrong endpoint returned an error response, the code tried to access r['tiles'][0] without checking if the tiles key existed, resulting in an unhelpful KeyError.

Changes

1. Fix endpoint overwriting: Use a separate fallback_endpoint variable for the stac_stats fallback, preserving the original titiler_endpoint for the main tile request
2. Add error handling: Check if 'tiles' exists in the response before accessing it
3. Improve error messages: Provide informative error messages based on the API response structure (dict errors with 'detail', list validation errors, or generic unexpected response)

Testing

Tested with the geo conda environment using:

• The actual download_naip.ipynb notebook scenario
• Direct stac_tile calls with Planetary Computer NAIP items
• Verified tiles are successfully returned after the fix

Example

Before:

KeyError: 'tiles'

After:

tiles = stac_tile(
    collection="naip",
    item="nd_m_4709963_se_14_060_20230701_20231116",
    assets=["image"],
    titiler_endpoint="planetary-computer"
)
# Returns: 'https://planetarycomputer.microsoft.com/api/data/v1/item/tiles/...'

Related Issues

Fixes opengeos/geoai#468

[Copilot]

Pull request overview

Adds defensive handling in stac_tile() when the TiTiler tilejson response does not include a "tiles" key, replacing an unhelpful KeyError with a more descriptive exception.

Changes:

• Detects missing "tiles" in the TiTiler response before indexing.
• Attempts to extract a helpful error message from common error response shapes.
• Raises a ValueError with details instead of failing with KeyError.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The common FastAPI/TiTiler validation error shape is a dict with a "detail" key whose value is a list of error dicts (e.g., {"detail": [{"loc": ..., "msg": ...}]}). In that case this branch will raise ValueError with the raw list repr, and the more user-friendly per-field formatting below is never used. Consider detecting isinstance(r.get('detail'), list) and formatting that list similarly (or delegating to a shared formatter) before falling back to str(r['detail']).

Suggested change

	error_msg = f"TiTiler endpoint error: {r['detail']}"
	detail = r.get("detail")
	# Common FastAPI/TiTiler shape: {"detail": [{"loc": ..., "msg": ...}, ...]}
	if isinstance(detail, list) and len(detail) > 0 and isinstance(detail[0], dict) and "msg" in detail[0]:
	errors = []
	for e in detail:
	loc = "->".join(str(x) for x in e.get("loc", []))
	msg = e.get("msg", "")
	errors.append(f"{loc}: {msg}")
	error_msg = f"TiTiler endpoint validation failed: {'; '.join(errors)}"
	else:
	error_msg = f"TiTiler endpoint error: {detail}"

[github-actions]

🚀 Deployed on https://6975bbd5f8d852ae24897b9e--opengeos.netlify.app