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

# Navigation: troubleshooting

> Fix low optical-flow quality, scale problems, lost frames and rejected configs in Navigation, and where to report a bug.

Start with the Navigation page: the estimator state, flow quality, flow rate, the scale source and the pre-arm rows usually point at the problem. Then read the plugin log on the drone:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin logs com.altnautica.navigation --lines 200
systemctl status 'ados-plugin-com-altnautica-navigation-*'
```

The plugin's output goes to its own log file under `/var/log/ados/plugins/`, not to the journal. `ados plugin logs` finds the file for you.

## Low optical-flow quality

Symptom: **Flow quality** on the Flow health card is below the gate (default 50), or the estimator reports `degraded`.

1. **Light.** The tracker needs both frames bright enough to find corners. Add light, or lower the camera frame rate so each frame gets more exposure. Mono global-shutter sensors cope better in low light.
2. **Texture.** Snow, water, fresh asphalt and sand have few features. Fly over textured ground. For testing over a safe area you can lower `flow_quality_min` in the plugin config; the flight controller still rejects bad samples itself.
3. **Yaw rate.** Fast yaw moves features out of view between frames. Slow the yaw, raise the frame rate or use a wider lens.
4. **Motion blur.** Fast horizontal flight with long exposure blurs corners. Shorten exposure or slow down.

## No frames

Symptom: **Flow rate** on the Flow health card drops to 0 and the estimator reports `failed`.

After 2 s without a frame the plugin marks the estimator `failed` and the companion `CRITICAL`, and it sends no flow. The flight controller's estimator then times the flow source out. Land, or switch back to GPS with your RC source-set switch.

On the ground, check that the agent's vision host still captures the downward camera (see [Multi-camera](https://docs.altnautica.com/drone-agent/multi-camera.md)) and look for camera errors in the agent's video logs.

## Scale source confusion

Symptom: in `optical_flow_degraded` the speed the flight controller computes is off by a large factor.

1. **Which rung is active?** The Sensors card shows the scale source:
   * `rangefinder`: a rangefinder reading is in use.
   * `baro`: `GLOBAL_POSITION_INT.relative_alt` or `VFR_HUD.alt` minus take-off.
   * `gps`: GPS height above the first 3D fix (only with `outdoor: true`).
   * `static`: no live height source; the plugin is on the 1.5 m fallback. The estimator is `degraded` and the **Altitude scale source** pre-arm row blocks.
2. **Barometer drift.** Indoor barometers drift, prop wash makes it worse, and air handling can move the reading by 1 to 2 m. Shield the barometer with foam and wait about 30 s after entering the space before you arm.
3. **GPS indoors.** If `outdoor` is on indoors, GPS height has no physical meaning. Turn `outdoor` off when you fly indoors.
4. **Static fallback.** Fix the height source before you fly. `optical_flow_degraded` on the static rung is not fit for flight.

## Rangefinder row blocks

Symptom: the **Rangefinder healthy** pre-arm row is red in `optical_flow`.

* "No fresh rangefinder reading.": no reading in the last 200 ms. For `fc_relay`, check that the flight controller publishes `DISTANCE_SENSOR`. For `tfluna_uart`, check the device path, the baud rate and the wiring; an open failure also shows as `rangefinderError`.
* "Rangefinder reading … outside …": the drone is below the sensor's minimum or above its maximum range.
* "Rangefinder required in this mode.": the topology is `none`. Set a topology, or switch the mode to `optical_flow_degraded`.

## Config rejected: camera orientation

Symptom: the plugin runs but stays disengaged in an optical-flow mode.

Both optical-flow modes need `camera.orientation` set to `downward` or `auto`. A `forward` or `side` orientation is rejected and leaves vision navigation disengaged. An unknown mode name does the same. Fix the key in the plugin config; the plugin restarts on the change.

## Do I need a rangefinder?

For `optical_flow`, yes: it is the scale source, and the pre-arm check expects a fresh reading. For `optical_flow_degraded`, no: scale comes from the flight controller's height, with more drift, especially above about 5 m.

## Night flight

Optical flow needs visible texture on the ground. In the dark it works only as well as the camera sees: add a downward light, or use an IR-sensitive camera with an IR illuminator, and test before you rely on it.

## Where do I file a bug?

Open an issue on the [ADOSExtensions repository](https://github.com/altnautica/ADOSExtensions/issues) with:

* the plugin log, from `ados plugin logs com.altnautica.navigation --lines 500` (the file is `/var/log/ados/plugins/com-altnautica-navigation-<hash>.log`);
* the output of `systemctl status 'ados-plugin-com-altnautica-navigation-*'`;
* the flight controller log covering the problem;
* the plugin config (`GET /api/plugins/com.altnautica.navigation/config`).

For problems outside the extension, see [Troubleshooting by area](https://docs.altnautica.com/operations/troubleshooting.md).

## Next steps

> [card] [Architecture](https://docs.altnautica.com/drone-agent/navigation-architecture.md)
>
> How the agent half is built.

> [card] [Modes and fallback](https://docs.altnautica.com/drone-agent/navigation-modes.md)
>
> Pre-arm checks and the scale ladder.


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