Troubleshooting

Troubleshooting

Start here when something doesn't work. Still stuck? FAQ, or open an issue.

---

Capture a Bluetooth debug log

For any Bluetooth problem, run the app from a terminal with HTBT_DEBUG=1 and paste the output into your issue:

# macOS
HTBT_DEBUG=1 /Applications/HTCommander.app/Contents/MacOS/HTCommander.UI.Avalonia

# Linux
HTBT_DEBUG=1 ./HTCommander-x86_64.AppImage

---

Can't connect / key or bonding error

• A stale pairing is the usual cause. Remove the pairing in your OS Bluetooth settings and re-pair the radio.
• If the app can't find the radio's data channel, toggle the radio's Bluetooth off/on.
• Make sure you paired in the OS first — the app does not pair for you (see Getting Started).

---

Winlink / BBS / App-TNC beacon "never connect"

This is almost always the "Digital mode" setting on the Benshi UV-PRO:

The radio's "Digital mode" must be OFF to use the app/TNC (KISS) path — Winlink, BBS, and the App-TNC beacon. Digital mode is only for the radio's built-in beacon and disables the TNC. The two are mutually exclusive.

The radio's built-in beacon, by contrast, needs Digital mode ON.

---

No received packets (TX works, RX dead)

A known firmware quirk: explicitly subscribing the DATA_RXD notification makes the radio stop delivering inbound packets (TX keeps working, RX goes dead). The app deliberately does not subscribe it — if you're on a current build and still see this, file an issue with an HTBT_DEBUG=1 log.

---

macOS: "app is damaged and can't be opened"

The app isn't notarized yet, so macOS quarantines the download. Remove the quarantine flag once:

xattr -dr com.apple.quarantine HTCommander.app
open HTCommander.app

The "damaged" message cannot be bypassed by right-clicking → Open — you must run the xattr command. (Tip: type xattr -dr com.apple.quarantine and drag the app into Terminal to fill in its path.)

Also: it's Apple Silicon only for now, and macOS will prompt for Bluetooth and Microphone permission on first run — allow both.

---

No audio / voice

• Both packages bundle PortAudio, so audio should work out of the box.
• On macOS, if audio is unavailable, install the system library: brew install portaudio.
• On Linux, ensure PipeWire / PulseAudio / ALSA is running.
• Confirm input/output devices and mic gain in the Settings tab.

---

APRS messages don't transmit

• APRS message TX goes through the hardware TNC, so Digital mode must be OFF.
• Transmit is gated on callsign + Allow-Transmit (Station tab) — confirm both are set.
• If no APRS channel is configured, messages send on the current channel; set an APRS channel for predictable behavior.

---

Reporting bugs

Open an issue — the bug-report form asks for your platform, app version, radio model, and steps. Attach an HTBT_DEBUG=1 log for Bluetooth issues.