Repository navigation
Troubleshooting
Most problems are one of five things: you don't have the hardware, the driver
can't do what you're asking, PATH differs between the GUI and your shell, a
third-party tool exited 0 without doing anything, or an interface is stuck.
Three commands answer most of it:
modules/00_deps.sh --check-versions # are the tools present
modules/01_iface.sh --list-tsv # what interfaces exist
modules/01_iface.sh --caps-tsv # what the driver supportsAnd to find out whether a module is broken or your invocation is:
modules/<n>_name.sh --selftest--selftest passes with no hardware attached. If it fails, that's a bug —
please report it.
Check it isn't a second instance. wifisting-gui is a GtkApplication and
single-instance. Launching it while one is running just activates the existing
window and exits 0 — which looks like a crash if you're watching exit codes.
pgrep -x wifisting-gui # already running?If that's not it, run it from a terminal to see the error:
./native/builddir/wifisting-guiA GTK assertion printed there is the cause. If it dies with no output at
all, that's a memory bug rather than a GTK one — worth reporting with the
output of dmesg | tail.
Rebuild if the source is newer than the binary:
meson compile -C native/builddirYou almost certainly have an Intel card. iwlwifi supports monitor mode
but not injection. The app detects this and tells you, rather than failing
quietly — but it will refuse to run injection modules.
modules/01_iface.sh --caps-tsvLook for whether injection is reported as supported. Monitor mode alone is not enough for anything offensive.
What you need: an adapter that can inject. Atheros AR9271 is what this was built and tested against — TP-Link WN722N v1, Alfa AWUS036NHA, Technoethical N150. See Hardware.
Still stuck? The app needs root for anything touching a radio. From a
shell, prefix with sudo.
pkexec resets PATH. This is the single most common "works for me" bug
in this project, and it cost a full debugging session to find the first time.
The GUI widens PATH at startup to include /usr/sbin and /sbin for
exactly this reason — iw lives in /usr/sbin on most distros. If you've
added tools somewhere else, they won't be found by a privileged action.
Diagnose by running the same verb both ways:
modules/<n>.sh --status-tsv
env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin modules/<n>.sh --status-tsvDifferent results means PATH. Please report it — the app should handle it.
This is the failure mode the project most wants to eliminate, and several modules carry explicit guards for it.
Known cases, all documented in the modules themselves:
| Tool | The problem |
|---|---|
hcxpcapngtool |
Exits 0 on a capture containing no handshake |
aireplay-ng, mdk4
|
Exit 0 whether or not a frame was transmitted |
wash |
Reports APs that aren't there under some drivers |
If a module reports success and the target is untouched, that's a bug worth
reporting — it's treated as a defect rather than a limitation. Include the
--caps-tsv output and the exact command.
A module died mid-capture, or you interrupted one.
sudo modules/01_iface.sh --restore-networkThat returns interfaces to managed mode and restores connectivity. The GUI offers the same recovery, and modules are meant to restore state on exit — if one doesn't, that's a bug.
If NetworkManager is fighting you, it will keep putting the interface back
into managed mode mid-capture. 01_iface.sh --kill-conflicts stops the
processes holding the interface.
The module file is missing or failed its syntax check. The startup message names which:
sudo bash wifisting.sh 2>&1 | grep -i 'syntax\|not loaded'Session logs carry the detail:
ls -t logs/session_*.log | head -1 | xargs tail -40Note: this label used to say [offline], which wrongly suggested a
hardware problem. It tests whether the module loaded, not whether your radio
is present.
Check which settings file your build uses. Each install keeps its own, and two copies of the project have two files:
ls -la state/state.iniIf you have more than one checkout, a change made in one won't appear in the other. That's by design — but it reads exactly like a saving bug.
Verify a save actually wrote:
grep -A5 '^\[settings\]' state/state.iniYou should see theme, density, splash and mono_size. If the section is
missing after pressing Save, the save failed and that's a bug.
Icons install on first run into ~/.local/share/icons. If that step was
skipped or interrupted:
./wifisting.shLaunching again re-installs any missing icons. To force a rebuild of the icon cache:
gtk-update-icon-cache -f ~/.local/share/icons/hicolorSet in Settings → Appearance → Splash. The still image is the default.
The animation is driven by gdk-pixbuf directly, so it needs no media
framework — if it doesn't play, the GIF is unreadable rather than a missing
dependency:
file native/resources/splash2.gifOlder CSR dongles silently drop BLE advertising data. They'll pair and work for Classic, then show nothing for BLE — with no error, because as far as the adapter is concerned nothing arrived.
hciconfig -a # is the adapter up and what is itA recent adapter is worth having. If Classic works and BLE doesn't, that's the usual cause.
An RTL-SDR can only receive. Sub-GHz transmission — replay attacks and similar — needs TX-capable hardware such as a HackRF.
The module should say so rather than appearing to work. If it doesn't, report it.
Also check the device isn't claimed by another process:
lsusbInclude:
-
Distro and version —
lsb_release -a -
Adapter —
modules/01_iface.sh --list-tsvand--caps-tsv - The exact command you ran, and the full output including stderr
-
Whether
--selftestpasses for that module
The caps output matters most. Most reports resolve to "this driver can't do that", and having it in the first message saves a round trip.
A module reporting success while doing nothing is the most valuable bug you can report. It's the failure class this project exists to eliminate.