FAQ and troubleshooting
Installing and starting
The AppImage does not start on my Linux
Usually one of two things. Either it is not executable, which chmod +x Homestead_*.AppImage fixes, or ticking Allow executing in the file's properties. Or the distribution has no WebKitGTK 4.1: AlmaLinux, Rocky and RHEL 8 and 9 ship 4.0 only, and the AppImage cannot run there at all. Ubuntu 22.04, Debian 12 and Fedora 36 and later are fine.
Windows says the app is unrecognised
The installer is not code-signed yet, so SmartScreen shows Windows protected your PC. Click More info, then Run anyway. If you want to be certain of what you are running, compare the file's SHA-256 against SHA256SUMS from the download page.
Is there a build for an Intel Mac?
No. The macOS build is for Apple Silicon (M1 and newer), macOS 11 and later.
The map
The basemap is blank
The basemap comes live from its provider, so it needs a connection. Without one, every layer you added still draws over a blank canvas. If you are online and it stays blank, pick OpenStreetMap again in the tree's Basemap section, or run Test on your own service in its edit dialog to see what the server actually says.
A layer is greyed out with “Zoom in to N”
The layer is too dense to draw at that zoom, because its tiles would be too heavy. Zoom in to the level it names and it appears. The threshold follows the densest part of the layer, so a national dataset may want a closer zoom than a city one.
My CSV or DXF opened but is not on the map
The file carries no coordinate system. Homestead takes it as WGS 84 if every coordinate fits inside longitude and latitude, and warns you under the file. When the numbers are projected metres it has no way of knowing which projection, so the layer stays a table. Convert it with a CRS, into a GeoPackage or a Shapefile with a .prj, and add that instead.
Rasters
“GDAL could not place this raster on the globe”
The raster has either no georeference or no coordinate system. A plain JPEG or PNG needs a world file, a .jgw, .pgw or .wld, and a .prj or .aux.xml beside it. A GeoTIFF exported without its projection needs one assigned, which in QGIS is Assign projection. A WebP takes its georeference from an .aux.xml and nothing else.
The raster draws only when I zoom in
Its pyramid is still building, or the build was cut short. The row shows the progress. If it reads Only zoom N+ draws until the pyramid is built and has a Retry link, click it. Pyramids build one at a time, so if you added several rasters together the later ones are waiting their turn.
Exports
The computer is sluggish while an export runs
Lower Processing threads in Settings. A job already running keeps the count it started with, and the next one picks up the new figure. The MBTiles options also have their own Parallel workers slider, under that same ceiling.
Can I stop an export?
Not from the window. It runs to the end in the background, and the status bar keeps it in view. It never writes anywhere but the file you chose, so a result you did not want is just one file to delete.
Will Tavak read the MBTiles I made?
Yes. WebP, PNG, PNG8 and JPEG tiles all import from the phone's Library as a raster dataset. WebP gives you the smallest file.
Surveys
A video shows a broken glyph instead of playing
On Linux the AppImage carries its own media plugins for H.264 and AAC. On Windows and macOS it uses the system player. A video in some codec other than the one the phone records may not play here. The file is still in the backup and the Files tab names it, so any player will open it.
The Info tab says “checksum mismatch”
The GeoPackage inside the ZIP does not match the checksum that metadata.json recorded at export. The survey still opens. Either the ZIP was altered after the phone wrote it, or it was copied incompletely. If in doubt, export it again from the phone.
Some photos read “not in this export”
Either the export was made without media, or the file was already missing on the phone. The rows and the positions are all there. It is only the picture that is not.
Files and privacy
Where does Homestead write?
Three places, and no others. The file you choose in a save dialog, which is an export, a project or a report. The data folder from Settings, for datasets fetched by address and for the tile cache. And the app's cache folder, for raster pyramids and the indexed copies of vector files. Your own files are never modified, and a backup is read exactly as it stands.
Does anything leave my machine?
Basemap tiles are fetched from the provider you chose, and a dataset you add by address is fetched from that address. Nothing else goes anywhere: no account, no telemetry, not even an update check.
How do I clear the caches?
The tile cache from Settings, with Clear the tile cache. The raster pyramids and the vector copies live in the app's cache folder and have no button yet, but deleting that folder while the app is closed is perfectly safe; everything is rebuilt the next time you open it.
Something is broken
Write to support@spatialize.dev and say what you did and what happened. A screenshot helps, and so does the version from the right-hand end of the menu bar.