Dire Wolf troubleshooting
Dire Wolf Debugging Notes
This page collects common Dire Wolf failure modes and practical debug steps. It assumes Dire Wolf is normally run with systemd. Command-line examples are included only for short diagnostic runs.
The upstream docs remain the primary reference for behavior and options: Dire Wolf repository and User Guide.
Quick copy/paste checklist
Use this when you need a fast first pass. It is systemd-first, with one optional foreground run for immediate error text.
Do not change multiple things at once. Capture baseline output first, then make one change, test again, and keep notes.
# 1) Confirm binary and service health
which direwolf
direwolf -h
systemctl status direwolf
journalctl -u direwolf --since "20 minutes ago" --no-pager
# 2) Confirm config path loaded by systemd
systemctl show direwolf -p ExecStart,User,Group,WorkingDirectory
# 3) Check audio devices and card mapping
aplay -l
arecord -l
cat /proc/asound/cards
# 4) Open mixer for the target card
alsamixer
# 5) Check KISS/AGW listener ports (replace placeholders)
ss -ltnp | grep -E "PORT1|PORT2|PORT3"
# 6) If issue appears after transmit, check for USB/audio reset events
journalctl -k --since "20 minutes ago" | grep -Ei "usb|snd|audio|reset|disconnect"
# 7) Optional one-time foreground debug run
direwolf -t 0 -c /opt/direwolf/direwolf.confCommon issues and fixes
| Issue | Typical symptom | What to check | Common fix |
|---|---|---|---|
| Wrong config path | Service exits immediately, cannot open config | ExecStart path and -c argument |
Move config to /opt/direwolf/ or update unit path to match real location. |
| Permissions on config/audio/GPIO | Permission denied, no PTT, no audio access | Service user/group and file/device ownership | Run as correct user; add user to needed groups (often audio, dialout, gpio-related groups). |
| Wrong audio device | No decode even with active channel | ALSA device names in config vs arecord -l |
Set correct ADEVICE values and retest in foreground. |
| Audio level mismatch | Poor/no packet decode, noisy demod | Input/output gain, mute state, and radio volume settings | Use alsamixer to confirm capture/playback channels are unmuted, then tune levels gradually while observing Dire Wolf decode output. |
| PTT method mismatch | Decodes RX but never transmits | PTT settings in config and physical interface wiring |
Verify RTS/DTR/GPIO mode, pin mapping, and interface cabling. |
| Port conflict (KISS/AGW) | Client cannot connect, bind failed | Configured TCP ports and listeners | Find conflicting process and choose unused ports. |
| Restart loop under systemd | Service flaps every few seconds | Initial failure in journalctl before restart |
Fix root cause first, then restart service; do not only increase RestartSec. |
| RFI impacts USB audio after transmit | Works at idle, then decode fails or device drops after TX | Kernel and service logs around transmit time | Add ferrites/chokes, improve cable routing/grounding, and reduce common-mode RF in station wiring. |
Distro variations to keep in mind
Group names and audio stack behavior vary by distribution. Verify local groups and membership before changing service users or permissions.
# Check whether common groups exist on this distro
getent group audio
getent group dialout
getent group uucp
getent group gpio
# Show current service account groups
id YOUR_USERNAME
Debian/Ubuntu often use audio and dialout. Fedora/RHEL-family
systems may use different serial or GPIO group names. Always match your local system.
Focused debug workflows
1) Service fails right after starting
systemctl status direwolf
journalctl -u direwolf -b --no-pager
systemctl show direwolf -p ExecStart,User,Group,WorkingDirectory
Confirm the executable path and config file path are valid for the service account.
View the journalctl output for the first few lines of failure text. Review
the direwolf logs right at startup for errors opening or parsing the config file, or opening
audio/PTT devices.
On this site, many examples assume config files are in /opt/direwolf/.
2a) Audio capture/playback trouble
arecord -l
aplay -l
cat /proc/asound/cards
# Short capture test from selected device
arecord -D plughw:0,0 -f S16_LE -r 48000 -c 1 -d 5 /tmp/dw-test.wav
aplay /tmp/dw-test.wav
If this capture test fails, there may be issues with the radio's output levels or the levels
on the USB audio device. Use alsamixer to check levels and mute state.
First ensure your radio levels are correct and audio/USB cables are connected correctly.
Then check your sound card's capture and playback levels (next step) and try the capture test again.
2b) Check mute and levels with alsamixer
# Open mixer for target card index
alsamixer -c 0
# Useful keys inside alsamixer:
# F4 = Capture view, F5 = All controls, M = mute/unmute, arrows = level adjustIn Capture view, verify the expected input is active and not muted. In Playback view, ensure output is not muted if your interface requires monitor/playback routing. If levels are too high, clipping can look like random decode failures.
If your device exposes Auto Gain Control (AGC), disable it for packet use. AGC can hurt decode consistency.
# 1) Open mixer for your sound card index
alsamixer -c 0
# 2) Press F5 to show all controls (or F4 for Capture view)
# 3) Use left/right arrows to find controls like:
# Auto Gain Control, AGC, Mic Boost, or similar
# 4) Disable the control:
# - For On/Off style controls, press M to toggle to Off
# - For value/enumerated controls, use up/down arrows until Off/Disabled
# 5) Press Esc to exit
# 6) Save mixer settings so they survive reboot
sudo alsactl storeControl names vary by USB codec, so check both Capture and All controls. If decode gets worse after a change, revert that one control and retest.
AGC indicator style varies by device. On many mixers, 00 means on and
MM means off (disabled). On others, expect labels like Off/Disabled.
3) KISS/AGW client cannot connect
# Replace with your configured KISS/AGW ports
ss -ltnp | grep -E "PORT1|PORT2|PORT3"
# Show process using a port
sudo lsof -iTCP -sTCP:LISTEN -n -P | grep PORT1Ensure only one process is bound to each required port and client software points to the same host/port.
4) Works until transmit, then audio fails (RFI)
# Look for USB/audio reset events around transmit time
journalctl -k --since "15 minutes ago" | grep -Ei "usb|snd|audio|reset|disconnect"
# Correlate with Dire Wolf service logs
journalctl -u direwolf --since "15 minutes ago"If failures align with transmit events, treat this as RF coupling first, then retest.
| Mitigation | Operator hint |
|---|---|
| Ferrites/chokes | Install ferrites on USB/audio/power leads near both equipment ends. |
| Cable routing | Keep interface cables away from feedline and high RF fields; avoid long parallel runs. |
| Station bonding | Improve bonding and common grounding to reduce common-mode current paths. |
| RF path control | Lower TX power for testing and verify feedline/common-mode choke effectiveness. |
| USB stability | Try a different USB port, shorter shielded cable, or powered hub. |
When packets are not decoding well
Decode quality is usually an RF or audio path issue, not only a software issue. Work in this order:
| Step | Action |
|---|---|
| 1 | Verify known on-air activity on the target frequency. |
| 2 | Confirm correct radio mode/filter/deviation for your channel plan. |
| 3 | Reduce clipping and avoid overdriving audio paths. |
| 4 | Retest with a short baseline config before adding advanced options. |
Collect useful data before asking for help
# Replace with your service name or instance
systemctl status direwolf
journalctl -u direwolf --since "30 minutes ago" --no-pager
# Runtime environment
uname -a
cat /etc/os-release
direwolf -h | head -n 5Include the exact command used to start Dire Wolf and a sanitized copy of the relevant config section.