Troubleshooting

Start with a health check — it diagnoses most of the below and can offer repairs:

aios doctor          # diagnose; `aios doctor --fix` offers to build / create the venv / pull a model

“No current location”

Map tools anchored to you (Nearest, Route from here) need a location, and none is assumed. Set one:

• On the map, centre the crosshair on you and click Set Home → From map centre (or From GPS location if a receiver has a fix); or aios geo here "<place>" / aios geo here <lat> <lon> / aios geo here gps.

A region you expected is missing after moving a data drive. A data drive carries the graph, which records which map regions are registered — so a drive from a unit with different maps still lists them. ApocOS drops those stale entries automatically at boot (the store is not on this image, so there is nothing to open) and registers whatever this image does carry. Nothing is deleted: put the drive back in its own unit and the region is registered again, with your field marks and bookmarks intact. The boot log records it as geo: dropped stale registration '<name>'.

With no location set, the dashboard’s measure from control greys out home / GPS and everything — Find Nearest and the Survey tools (Sightlines / Best site / Signal) alike — measures from the map centre. Every result says which anchor it used.

”No elevation / no DEM tile here”

Terrain tools (Sightlines, Signal, elevation, line-of-sight) need SRTM elevation data for the area:

aios geo dem fetch <region>      # or: aios geo dem fetch --at <lat,lon>

Check coverage with aios geo list (each region shows its elevation tile count) or aios geo dem list.

”No GPS fix” / the GPS button is missing

GPS is optional hardware, read from gpsd or a serial receiver. aios gps status explains the state:

• No receiver — plug one in and start gpsd, or set AIOS_GPS_SERIAL=/dev/ttyACM0.
• Acquiring — the receiver is present but hasn’t locked yet; try near a window/outdoors.
• Permission denied on /dev/ttyACM0 — add yourself to the dialout group: sudo usermod -aG dialout $USER, then log out and back in.

The dashboard’s Go GPS button only appears when a receiver is detected.

A region is loaded but POIs / a new layer are missing

Map kinds only populate when a region is ingested. After upgrading (new kinds are added over time), refresh the region:

aios geo update <region>            # re-ingest; --reparse re-parses the cached PBF offline (no download)

Also check the POI layers panel — only ticked layers are drawn.

The assistant is slow, or refuses / loops

• aios status shows the selected model and why. Small machines get a small model; a very small model can struggle. Override with AIOS_LLM_MODEL=<model> if you’ve pulled a larger one.
• Pull a model with the System tab, or aios doctor --fix.
• Answers are grounded in local data — if the graph is empty, index a project first: aios reindex <dir>.

The dashboard won’t load

• Make sure the server is running (aios serve) and you’re using the printed URL (http://127.0.0.1:8017 by default).
• If the port is busy, start on another: aios serve --port 8099.
• After changing server code, restart aios serve — a browser refresh reloads static assets, not the Python server.

Data disk isn’t detected (live boot)

aios data status     # where your data store resolves (pinned / labelled disk / ephemeral)
aios data disks      # candidate disks

A disk is only used for data if it’s labelled AIOS_DATA (or pinned). A disk is never formatted without an explicit aios data init <dev>. An ephemeral fallback (no persistence) is always announced loudly.