> For the complete documentation index, see [llms.txt](https://docs.anthriq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.anthriq.com/bxi-studio/common-issues.md).

# Troubleshooting

User-facing fixes for the problems people hit most often inside the app.

## Device not found

**Symptoms:** No devices appear in the Available Devices list after scanning.

**Fixes:**

* Confirm the device is powered on and the LED indicator is active.
* Verify your computer and the device are on the same local network.
* Click the **Retry** button to rescan.
* Check that no firewall is blocking local network discovery.
* For Wi-Fi devices, confirm the device has joined your network. See [Pair a new Wi-Fi device](/bxi-studio/device-discovery.md).
* Restart the BXI Studio app.

## Connection failed

**Symptoms:** Clicking a device starts connection but fails with an error.

**Fixes:**

* The device may be connected to another BXI Studio instance: only one connection per device is supported.
* Check device battery level. Low battery can cause connection drops.
* Move closer to the device if using Wi-Fi.
* Restart the device and try again.

## Calibration failed or stuck

**Symptoms:** Calibration progress stops or shows an error.

**Fixes:**

* Place the headset on a flat surface. Do not wear it during calibration.
* Check that no electrodes are physically blocked or jammed.
* Reduce calibration cycles to 1 for a quick test.
* If motors are unresponsive, disconnect and reconnect the device.
* Check battery level. Calibration requires motor power.

## Poor impedance (red electrodes)

**Symptoms:** Most or all electrodes show red (> 200 kΩ) on the Electrode Configuration screen.

**Fixes:**

* Hair is the most common cause. Part hair at each electrode location.
* Move electrodes down to increase scalp pressure.
* Apply conductive gel to electrode tips if available.
* Confirm the headset is positioned correctly. See [Wear the headset](/bxi-studio/configure/wear-headset.md).
* Use the **reset** button on individual electrodes and readjust from position 0.
* Moderate (yellow) impedance is acceptable for most use cases.

## Recording will not start

**Symptoms:** The Start Recording button does not respond or is disabled.

**Fixes:**

* **Start Plotting** must be active first. You cannot record without live data.
* Select at least one viewport in the recording dropdown (all are pre-selected by default).
* Confirm a device is connected and streaming.
* Check that you are not already in a recording session.

## Layout selector unresponsive

**Symptoms:** The layout icon is grayed out or does not respond to clicks.

**Fixes:**

* Layout changes are locked during recording. Stop the recording first.
* Click the layout icon (do not long-press) to open the dropdown.
* If the dropdown appears but clicking a layout does nothing, stop and restart plotting.

## App crashes on launch

**Symptoms:** BXI Studio opens briefly then closes, or shows a white screen.

**Fixes:**

* Versions 1.0.13–1.0.15 had a known build issue. Update to 1.0.16 or later.
* Clear the app cache:
  * macOS: `~/Library/Application Support/BXI Studio/`
  * Linux: `~/.config/BXI Studio/`
* Reinstall from the latest download.
* Check system requirements. The app requires macOS 12+ or Ubuntu 22.04+.

## OTA update failed (checksum error)

**Symptoms:** Update downloads but fails with a verification error.

**Fixes:**

* This occurs when the update manifest on the server does not match the binary.
* Wait for the update to be re-published with correct checksums.
* Dismiss the update notification and keep using the current version.
* Manual download from the release page is the fallback.

## Walkthrough automation stuck

**Symptoms:** The in-app walkthrough button stops at a step and does not proceed.

**Fixes:**

* The walkthrough uses GUI clicks. If a modal is blocking, it may time out.
* Close any open modals or overlays manually. The walkthrough resumes.
* Stop and restart the walkthrough.
* Some steps require a real device connection. The walkthrough works best in demo mode or with the firmware emulator running.

## Contact support

For issues beyond this list, see [Support](/bxi-studio/support.md).