Appendix C: Troubleshooting

Setup issues

Problem	Cause	Fix
"Generate Project Structure" does nothing	Output directory is blank or doesn't exist	Set a valid output directory in the Setup panel and click Save Settings first
CRS warning after setting anchor	Anchor is at 0,0 or in the ocean	Pan the canvas to your actual map area before clicking "Set Anchor at Canvas Center"
Settings don't persist between sessions	`hexmosaic.project.json` wasn't saved	Click "Save Settings" before closing QGIS

Problem	Cause	Fix
AOI exceeds hex limit warning	Width or height > 99 hexes	Reduce the size or tick "Allow experimental AOI sizes" (but note the game limit is 120 x 120)
"Use Canvas Extent" gives unexpected size	Canvas is zoomed too far in or out	Zoom to roughly the area you want, then click the button
POI geocoding fails	Nominatim rate limit or no internet	Wait a moment and retry, or add lat/lon columns to your CSV manually

Problem	Cause	Fix
Grid takes very long to generate	AOI is very large (> 100 x 100 hexes)	Use a smaller AOI or segment it into tiles
Hex Tiles layer is empty	AOI polygon has no area or wrong CRS	Recreate the AOI after setting the project CRS

Problem	Cause	Fix
DEM download fails with 401	Missing or invalid API key	Add your OpenTopography API key in the Setup panel
DEM download fails with timeout	Large area or slow connection	Try a lower-resolution source (SRTMGL3) or a smaller AOI
Hex elevation layer has all zeros	DEM doesn't overlap the hex grid	Check that the DEM covers the same area as your AOI
No styles in the dropdown	Styles directory is wrong	Check the styles directory path in Setup and click Refresh

Problem	Cause	Fix
Download times out	Overpass API is overloaded	Wait a few minutes and click "Refresh Last". The plugin tries 3 mirrors automatically.
Empty layers after download	AOI is in an area with sparse OSM coverage	Normal for remote regions. Check the data on openstreetmap.org first.
"Import Local" doesn't work	File format not recognized	Use GeoJSON, Shapefile, or GeoPackage. Other formats may not be supported.

Problem	Cause	Fix
Classes generate empty layers	OSM data doesn't contain matching tags	Check that you downloaded the right themes (e.g. Landcover for forest)
Wrong class wins a hex	Priority conflict	Open `hexmosaic_profile.json` and adjust the priority values. Higher numbers win.
Automation is slow	Many classes + large grid	Generate only the classes you need using "Generate Selected Classes"

Problem	Cause	Fix
"Compute" shows 0 x 0 pixels	No AOI selected	Select an AOI from the dropdown
Exported image is blank	No layers checked in the export tree	Check the layers you want to include, or use a preset
Image is very large (> 1 GB)	Full 120 x 120 hex map at full resolution	This is expected for maximum-size maps. Use JPG format to reduce file size.
Colors look wrong in export	Layer rendering order	Reorder layers in the QGIS Layers panel — layers higher in the list draw on top

Check the Log panel (panel 10) for detailed error messages and file paths after any operation.
Save your settings frequently. The plugin stores UI state in hexmosaic.project.json — if QGIS crashes, your settings are preserved.
QGIS version compatibility. If you see PyQt import errors, make sure you're running QGIS 3.22 or later. The plugin supports both Qt 5 and Qt 6.