Troubleshooting

Organised by symptom, because that is how trouble presents — you do not know which component is at fault yet, that is the whole problem. Find what you are seeing; the fix names the component.

Every entry under Installing and Running was observed on a real machine (the VM verification campaigns or field use), not imagined. The Audio entries point into the audio-routing guide, which says for each one whether it was measured on the bench or is documented behaviour not yet reproduced here. Where a fix is distribution-specific it says so.

Installing

• An install stops because the disk is full, or the plan quotes more than you have — what each profile, the build cache and each data layer cost, and what you can delete to get space back (~/.cache/hammunition/build, sudo apt clean).
• The dry run seems to hang, or an install sits silent — the plan is checking publishers over the network; on a terminal it says what it is waiting on, and HAMMUNITION_PROGRESS=1 makes it say so when stderr is not one.
• An install stops at a sudo password prompt for hours — the ticket expired during a long conversion; the engine now keeps it alive.
• A source build fails to fetch — HTTP 404 — a pinned upstream URL moved. Report it; run the URL sweep.
• A git build stops in a text editor — your own tag.gpgsign setting; fixed in the engine from v0.20.0.
• apt refuses with "held broken packages" on Parrot — the backports-vs-base development-library skew. Install the -dev packages from backports.
• python3 -m venv fails with ensurepip — a Debian netinst without python3-venv.
• A vendor .deb is refused for a file collision — wsjtx-improved versus the distribution's wsjtx-data, by design.
• A package is "refused by name" for a backend/repo — not a failure; the engine will not shim an unsupported combination.

Running

• Where is the log of what just happened? — every install, hardware or maps run leaves one; hammunition logs --last.

• A GUI comes up blank or without decorations — Wayland; switch the session to X11. The classic is WSJT-X on a Pi.

• Permission denied on a serial device — you were added to dialout at install, but group membership needs a fresh login.
• A venv-installed program is "not found" — ~/.local/bin reaches PATH on next login; open a new shell.
• rnstatus says "Could not get RNS status" — it could not read the shared instance it attached to; look at who owns the @rns/ socket and at ~/.reticulum/logfile.
• Another Reticulum program owns the shared instance — hammunition-rnsd attached to it instead of starting its own; stop one of the two.
• Two laptops running Reticulum do not see each other — no peers on the AutoInterface: the service, link-local IPv6, UDP 29716 and 42671, or a network that isolates its devices.
• rnodeconf cannot open the RNode's port — dialout, a parked device, or another program holding it.
• "Address family not supported by protocol" from a packet program — Linux 7.1 removed kernel AX.25; the userspace path still works.
• A CH340 serial device vanishes the moment it is plugged in — brltty claimed it as a braille display. Ubuntu 24.04 and Mint, behind one kind of hub; measured per target.
• The FT8 waterfall is silent — audio routing, covered in first contact.
• FT8 decodes nothing on a busy band — the clock is more than a second out. timedatectl; with no network, a GPS keeps it, by a route that depends on the time daemon.
• GPS dead after the laptop slept — the receiver is not re-enumerated on resume and gpsd keeps a quiet tty. hammunition hardware apply installs the resume step; park and wake by hand if it is still dead.
• A tray switch does nothing, or a group says "update hammunition-tray" — no polkit agent in the session, or an older helper than the panel.
• No position in QMapShack or the browser map — the GPS tether is not running (it starts at your next login after install), or gpsd has no fix.
• The browser map has no Route control — GraphHopper's graph is not installed, or the router stopped.
• A program cannot reach the radio, or the radio behaves erratically — two programs have the serial port open. One owns it; the rest ask it.
• Everyone is heard, nobody hears you — transmit audio level. No ALC action.
• rtl_test says the dongle is busy — the kernel's TV driver claimed it first.
• Direwolf or ardopcf: device busy — PipeWire has the sound card; set its profile to Off.

Audio and digital modes

Symptom first; each links to the entry in Radio audio or the digital-modes guide.

• The waterfall is flat or black — the program is recording from the wrong source. wpctl status shows which.
• The waterfall is solid colour and decodes nothing — the input is clipping; lower the radio's USB output level.
• Tune keys the radio but shows no power — wrong output device, or the radio's data-mode audio source is the mic jack.
• The radio's sound card is not in the program's list — cat /proc/asound/cards says whether the kernel sees it at all.
• Desktop sounds go out over the air, or the radio keys by itself — the radio became the default output.
• SSTV pictures slant — sound card clock error; calibrate once per card.
• It worked until I opened a second program — one ham program per radio per session.
• All sound stopped after installing something — a package pulled in pulseaudio, which removes pipewire-alsa. The planned removal was measured on the bench, where Hammunition refused it (issue #61).
• WSJT-X's Test CAT fails — test the radio with rigctl first; then look for a second program holding the serial port.

When nothing here fits

Each program's own known problems and real support channel are on its page under docs/packages/ — the known_problems and upstream_support fields, straight from the manifest. That is where a problem specific to one program, rather than to installing or launching it, belongs.