Start with the run’s data/pipeline_runs/<run-id>/report.md. Find the first
FAIL, DEGRADED or unexpected SKIPPED step, then read the lines with the
same [QS-NN] tag in run.log.
FAIL stops dependent steps. DEGRADED carries on without a source; a later
PASS does not undo that (a DSM-only run stays DSM-only).
If no numbered report was created, inspect the printed queue directory:
state.json records task status/errors, and attempts/ contains executor
logs when a subprocess started. A queue succeeded result does not erase
DEGRADED steps in the pipeline report.
For status commands, lock locations and deliberate crash recovery, use Evidence, conflicts and recovery. The local coordinator requires no cloud credentials; a later fetch failure may still require a LINZ key.
Namespace has no attribute include_imageryThe local queue must persist the imagery choice and pass it to the pipeline worker. Older tasks without that option default to including imagery. Update the checkout with the queue-option fix, restart the web panel, create a new estimate and submit again. Reinstalling dependencies does not fix this error. Completed outline downloads remain cached.
If a worker crashes between numbered steps, the run report may remain
RUNNING even though the job failed. Read the job’s stdout.log or the
queue’s attempt log for the traceback; pending steps did not run.
data/data/ holds tracked files you cannot fetch again: roof labels, benchmark and
verdict data, trained models. Do not delete it or a whole region directory
as a troubleshooting step. See Cleaning up
before removing generated inputs or untracked work.
Check command -v gdalbuildvrt gdal_translate in the terminal used to start
the panel. If both resolve there, reinstalling requirements or Homebrew tools
does not address the failure. Web jobs must inherit the panel’s environment,
including PATH, when adding the source layers pinned by the estimate.
Update the checkout with the environment-inheritance fix in
the job runner, stop and restart the
panel from that terminal, then create a fresh estimate and retry.
Existing panel processes do not reload Python changes.
If either command is genuinely missing, follow the system-tool setup in Local setup; Python requirements do not install GDAL CLI tools. No cached data needs to be deleted for this preflight failure.
Cannot decode required LERC terrain tiles: system GDAL’s TIFF reader cannot
decode LERC, even if liblerc is installed. The pipeline tests this on a
small offline file before fetching, for both Rasterio and system GDAL.
brew bundle --file=Brewfilegdal-bin, then run the check:.venv/bin/python -c 'from src.s3_rasters import require_raster_support; require_raster_support()'
The pipeline tries GTiff, then LIBERTIFF. To force one:
SOLAR_TIFF_READER=GTiff bash quickstart.sh
SOLAR_TIFF_READER=LIBERTIFF bash quickstart.sh
Values: auto, GTiff, LIBERTIFF. Tested on macOS with GDAL 3.13.3 and
Rasterio 1.5.2; untested on Ubuntu/WSL. Don’t set GDAL_SKIP=GTiff
globally: it breaks TIFF writing.
If Rasterio fails, reinstall requirements.txt into the interpreter in the
report. System GDAL and Rasterio’s bundled GDAL are separate; upgrading one
does not fix the other. Nothing is installed automatically.
Install the requirements into the Python named in the report (usually .venv):
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -c 'import matplotlib.colors; print(matplotlib.__version__)'
On Windows Git Bash use .venv/Scripts/python.exe. Always run pip as
<python> -m pip so it installs into the same environment.
LINZ_API_KEY is not setExport LINZ_API_KEY in the shell, or add LINZ_API_KEY=... to .env. See
LINZ credentials.
Confirm the locality boundary and LINZ metadata service are available. The resolver selects a DSM whose published extent contains the complete build bbox; it does not use a partial or neighboring survey. If no DSM covers the area, the build warns and uses a synthetic surface with guessed roof pitches.
Area-specific layers are discovered automatically and cached under
data/sources/linz/. Retry after a transient LINZ failure; if the selected
metadata appears incorrect, inspect the cached metadata and the LINZ layer
extent before changing the resolver.
LINZ export creation timed outRaster-export creation waits up to 120 seconds for LINZ, matching the council-outline exporter. Retry the build if LINZ does not respond in time; completed raster mosaics are reused. Creation requests are not automatically retried because LINZ may have created a job before its response timed out. See src/fetch_data.py.
The key works for web services but cannot create exports. LINZ cannot add permissions to a key: make a new one with export permission and replace it. See src/fetch_data.py.
A locality’s building outlines come from a per-council Exports API
GeoPackage. Without export permission, or when the LINZ export fails or
times out (30 minutes), preflight prints council GeoPackage unavailable
(...); using LINZ WFS and carries on with WFS. locality.json records the
reason under outline_source.fallback_reason. To retry the export:
.venv/bin/python src/linz_exports.py fetch "<Council name>" --refresh.
See Building outlines source.
deprecated warning for a region nameThe region is a legacy config.REGIONS bounding-box name. It still builds.
For new work use a LINZ locality id; see Choosing an area.
outside-extentCheck the layer ID and that it covers the bbox. Some imagery chunks outside coverage are normal at the edge of a survey; a DSM wholly outside is not. DSM/DEM layers are Grid, imagery is Raster. Don’t change the bbox or layer just to silence it.
Fetch returned zero building outlinesCheck the region name, bbox order and that it covers buildings in NZ.
The run carries on with the 1 m DSM: coarser geometry and gates, and the heat
map may be empty. Check lidar_tile_index_layer, pointcloud_bulk_url and
pointcloud_tile_year all describe the same survey. Never point at another
survey’s store. See src/fetch_pointcloud_regions.py.
Error in sys.excepthookOlder layout workers left Rasterio datasets open until interpreter teardown, after their Python callbacks were unavailable. Current workers close their DSM and imagery handles through a multiprocessing finalizer before teardown. Update the checkout and retry the build; no extra Python package is needed. See src/build_layout_geojson.py.
Install tippecanoe, tile-join and tippecanoe-decode, open a new
terminal and check with command -v. macOS: brew bundle --file=Brewfile.
Ubuntu/WSL: build it.
Read the [QS-17] or [QS-18] lines. Emit needs the region’s solar and
layout GeoJSON, the heat-map raster and sidecar, and its build keys. The
required fields are in tests/test_output_contract.py.
no_estimate features in panel_layouts.pmtiles are intended: the outline of
a building with no estimate. Don’t remove them.
Check map-preview-server.log and the [QS-21] lines. Confirm
data/buildings.pmtiles exists and is not empty and the port is free. The
server listens on 127.0.0.1 only. A good range probe returns HTTP 206, not
200.
Step 15 reports how many buildings rendered from LiDAR. Zero means no usable point cloud; the rest of the map still works. Check step 02’s coverage.
Expected: the address search tries addresses/index.json before
addresses.json; the static preview has no /api/refit; heat-map tiles
outside the area don’t exist. If nothing shows at all, check the start
location and turn on Panel Layout.
Share the first failing [QS-NN] error, its run.log lines, the non-secret
parts of report.md (area, bbox, survey, statuses, exit codes), your OS and
which Python you used. Never share .env or the key.