> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation troubleshooting

> Resolve setup, localization, mission, and lifecycle problems.

Start with `nav.status()`, then inspect the [API contract](/navigation/api-reference).
During a motion problem, use the robot's e-stop when an immediate halt is needed;
a network command depends on a working connection.

| Symptom | What to check |
| - | - |
| Notebook imports fail | Keep the CLI dev session open and select its workspace `.venv` kernel. Do not install PointNav into the laptop to fix a Nexus import. |
| `NavNotInstalled` | Navigation is opt-in during provisioning. Ask the robot operator to check its PointNav installation and imports. |
| First start fails compiling a native backend | The robot needs CMake, GNU make, a C++17 compiler, and Eigen3 headers. Provisioning does not verify these prerequisites; first use compiles on the robot. |
| Construction options are unsupported | Update both Edge Comms and PointNav; confirm the served capabilities match the client. |
| `[InstanceError]` while attaching with options | A Nav already exists. Attach without options to inspect it, or coordinate shutdown before changing its configuration. |
| `[InstanceError]` on an old handle | The robot or Nav was replaced. Recreate the robot handle after a robot restart, then attach navigation again. |
| Expected map/path missing | Catalogs return one page. Check subsequent pages, account/cluster, map ID, and map build status. Names may be duplicated. |
| `UnknownMission` | Use a `path_id` from `list_paths` for the active map. A semantic label belongs in `find`/`plan`, not in `run_mission` as a saved mission name. |
| `find` returns no matches | The map may lack that semantic label. Inspect another label or use a verified map coordinate. Do not assume a live-camera detection is a map coordinate. |
| Localization times out or the marker is wrong | Verify the map matches the physical area, sensors are available, and the robot runtime can reach GRID cloud. Check the viewer and localization diagnostics before retrying. Do not drive using an incorrect pose. |
| A second mission is refused | Only one mission runs at a time. Cancel if appropriate, then wait until `mission_running` is false. |
| Non-blocking return value has no `.wait()` | No remote Run wrapper is provided. Poll `nav.status()` and inspect `nav.result()`. |
| Mission ended with no result | Check `nav.telemetry()["status"]["error"]` and `nav.events()` before stopping or starting another run. Missing result is not success. |
| Camera/GRID cloud loop stopped but robot still drives | Non-blocking execution lives on the robot. Call `cancel_mission()`; include cancellation cleanup in observation loops. |
| Method call timed out | The robot may have received it. Inspect state before repeating a motion request. |
| `nav.view()` fails | The same computer needs the CLI dev session and its local viewer URL. A bare remote connection does not supply that viewer. |
| Editor has no maps | Check the CLI account/cluster, Refresh, and Load more maps. Only COMPLETED maps can be selected. |
| Waypoints disappeared on another computer | Save waypoints is a local library. Save mission to GRID cloud is the shared saved route. |
| Save mission is disabled | Supply a name, start and destination; Plan route after the most recent edits. |
| Viewer is connected but pose is stale | Inspect pose age and localization health; connectivity alone does not prove localization is current. |
| YAML path is missing | Paths passed as cfg are resolved on the robot, not uploaded from your laptop. |
| Config did not change after mutating nav.config | The dictionary is a snapshot. Release the old Nav and construct a new one with explicit settings. |
| Can't switch map with `start` | Use `set_map` while active, or stop then start with the new UUID. The robot must physically be in that mapped area. |

## Collect useful evidence

Record the robot name, map ID, installed versions, failing call, exception text,
and `nav.status().to_dict()`. For mission problems, include the run identifier,
result, and recent events before cleanup. The live viewer provides map and
terminal diagnostics; `telemetry` and `log_chunk` support programmatic access.
Keep credentials out of notebooks and shared logs.

## Retry deliberately

Re-localizing, restarting navigation, and re-running a mission are separate
actions. `stop(retain_localization=True)` preserves only an inert pose seed;
`start(map_id=...)` still validates it with a fresh cloud fix. It does not resume
the old mission. After the robot moves, plan a fresh route to the remaining goals.


## Related topics

- [Chapter 1 — Run your first mission](/navigation/first-mission.md)
- [Agentic navigation](/cli/agentic-navigation.md)
- [Configure navigation](/navigation/configuration.md)
- [Navigation data schemas](/navigation/data-types.md)
- [Navigation API contract](/navigation/api-reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.