Troubleshooting

This page covers the most common problems you may run into when using ARIS, along with their solutions. If your issue is not listed here, check the FAQ or contact support.

Connection Issues

Cannot connect to backend

Verify that the host address and port are correct in your connection settings. Make sure your firewall allows traffic on the configured port, and confirm that the Raspberry Pi (or other backend host) is on the same local network as your device.

WebSocket disconnects

ARIS uses automatic reconnection with exponential backoff. The app will attempt up to five reconnection attempts before marking the connection as failed. If reconnections keep failing, check your network stability and confirm the backend process is still running.

Understanding connection health states

The ConnectionStateBanner at the top of the screen shows live connection health. The three states are:

Healthy — connected and communicating normally.
Reconnecting — the connection dropped and ARIS is attempting to restore it.
Degraded — multiple reconnection attempts have failed; manual intervention may be needed.

INDI Driver Issues

Driver will not load

Make sure FIFO mode is enabled in the INDI systemd service configuration. Without FIFO mode, ARIS cannot dynamically load drivers at runtime.

ASI camera not detected

Check the USB cable connection and try unplugging and replugging the camera. Note that the serial port assignment may change (for example, from /dev/ttyACM0 to /dev/ttyACM1) after a reconnect.

ASI SDK version too old

If you encounter compatibility errors with your ASI camera, upgrade to the latest ASI SDK by installing the updated packages from the Debian repository. Versions older than SDK 1.41 may not support newer camera models.

Guiding Issues

PHD2 hangs with multiple cameras

When running multiple ZWO cameras, use the PHD2 native ZWO driver instead of INDI Camera mode. The INDI path can cause conflicts when two cameras share the same driver.

PHD2 mount configuration

The INDImount setting must be present in both [profile/1/indi] and [profile/1/scope] sections of the PHD2 configuration. If it is missing from either section, PHD2 will not be able to issue guide corrections.

Guide star lost

Check the guide star SNR (signal-to-noise ratio). If it is too low, increase the guide exposure time or select a brighter star. Poor seeing conditions can also cause intermittent star loss.

Imaging Issues

Captures timing out

Check the USB bandwidth setting on your camera. If multiple USB devices share the same hub, reduce the bandwidth allocation or lower the capture resolution to avoid contention.

Images appear black

Verify that the exposure time and gain are set to reasonable values for your target. Also check that the cooler has reached the target temperature — some cameras produce dark frames if the sensor is not stabilized.

Download fails

Check your network connection between the app and the backend. If the download was interrupted, ARIS will offer a retry option. Persistent failures may indicate the backend storage is full.

iOS and Mobile Issues

Always use release builds for physical devices

Debug builds require a connected debugger and will crash on physical devices without one. Always deploy with --release when installing on an iPhone or iPad.

Flutter Developer Mode check fails

On certain iOS versions, the Developer Mode verification prompt may not appear automatically. Open Settings on the device, navigate to Privacy and Security, and enable Developer Mode manually before deploying.