Troubleshooting

Short answers for the failures that show up first with public hosts. Background: How it works. Endpoints: Example sources.

Prefer compute_with_policy

Lazy create_array only fetches when you compute. Plain .compute() uses Dask’s default thread pool (often ~CPU count), which can leave fetch headroom unused. Prefer:

from tilearray import compute_with_policy

result = compute_with_policy(da)          # or compute_with_policy(da.mean())

create_array stores fetch policy on da.attrs; compute_with_policy reads it automatically. You do not need to pass max_concurrent by hand.

Environment Agency WCS

Symptom	Likely cause	What to do
Empty / invalid coverage	CoverageId ≠ URL path slug	Use the GetCapabilities id (e.g. UUID__Lidar_Composite_Elevation_DTM_1m), or WCSConfig.for_ea_dsp with the id from Example sources
Many 403s / hard fail mid-mosaic	Burst above the EA ceiling	Keep AIMD ceiling at 10 (the EA preset). Do not raise max_concurrent_requests for county-scale cold mosaics
Slow multi-tile mosaic	Dask workers << fetch ceiling	Use compute_with_policy (or create_array(..., compute=True))

OpenStreetMap XYZ

• Stay on XYZConfig.for_openstreetmap (identifiable User-Agent, max 2 in-flight, ~2 req/s).

• Palette PNGs often decode as single-band grayscale, not RGB. A small London window at z16 is about (1024, 512), not (256, 256).

• Attribute © OpenStreetMap contributors when displaying imagery.

NASA GIBS XYZ

• Template order is {z}/{y}/{x} (row before column), unlike OSM {z}/{x}/{y}.

• Wrong order yields empty or scrambled mosaics — copy the template from Example sources / NASA GIBS XYZ — Blue Marble.

WMS (EA Vegetation Object Model)

• Layer names are year-suffixed (Vegetation_Object_Model_2022, …). Confirm the year in GetCapabilities before hard-coding.

• Transparent PNG GetMap responses decode to RGBA (4 bands).

Failures are loud

After retries, a failed tile raises tilearray.NetworkError. Mosaics do not succeed with silent NaN holes; sibling in-flight tile fetches abort when the session fails hard.

Disk cache

Pass cache_dir= to create_array / load_array to reuse tile bytes across runs. Warm reads sniff the body when response headers lie (e.g. multipart WCS). Clear the directory if you change decode expectations or suspect corrupt cache entries.

Custom endpoints

Use WCSConfig.from_url / WMSConfig.from_url / WMTSConfig.from_url / XYZConfig.from_url and tune FetchPolicy / config knobs (max_concurrent_requests, rate_limit_per_second, AIMD fields). Presets exist only for known host quirks (EA DSP WCS, OSMF XYZ) — they are not a catalogue of every public layer.