Skip to content

Troubleshooting

Fin edited this page Nov 14, 2026 · 2 revisions

Troubleshooting

Look at the VERDICT block

Every pass ends with a verdict in the run log. Start every diagnosis there. Its counters separate a console that refused from a console that was never there.

Line What it means
console probes heard : NONE No StreetPass probe was received. A console may still be present, because one that has already met you stops probing at you.
console OUI on air Frames from a Nintendo address were seen even though no probe arrived. The console is there and is not talking to us.
frames sent / ACKed Whether the radio transmitted, and whether anything acknowledged it.
how the pass ended Timeout, our own decline, or a completed exchange.
a decline reason We chose not to serve: blocked, in cooldown, or nothing to offer.

Nothing happens at all

Wait longer first, give it ten minutes before deciding it failed.

Then check these in order:

  1. Is the console enabled for StreetPass? At least one title must have it on.
  2. Have you already exchanged with this console? Then this is expected. See The MAC filter, rotate identity and try again.
  3. Is the radio transmitting? Run sudo ./scripts/tuxchange-probe. If the console never reacts to a direct probe, the radio is the problem.
  4. Is it an ath9k card in active monitor mode? See Hardware. A passive monitor interface cannot ACK, and the console abandons the handshake.

console probes heard : NONE but the console is right there

The verdict distinguishes two situations:

  • console OUI on air is also present: the console is transmitting but not probing at us. This is almost always the MAC filter.
  • Nothing is on air either: check the console is awake and enabled, and that you are watching the right channels.

The handshake starts and then stops

The console engages and then goes quiet without completing. Normally this recovers by itself: Tuxchange sends a synthesised 0xF2 object to force a rescan, which recovered 139 of 142 stalled onsets against 0 of 35 without it. If you have turned that off with --no-silent-recovery, turn it back on.

If it never recovers, suspect ACKs, meaning the interface is not really in active monitor mode.

No green LED but the exchange completed

The green LED means cecd accepted the message. The game applies its own validation on top, so a message can be accepted at the CEC layer and still not appear in Mii Plaza. Common causes are a Mii that fails the plaza's own gate, or a message whose HMAC does not verify under that title's key.

Check the store: does the message you sent verify? Does the title's key in tuxchange.keys match the console you are exchanging with?

Green LED, but nothing in Mii Plaza

The plaza deduplicates on Mii identity and ignores the encounter list, so re-sending the same Mii to a console that already has it does nothing.

The service will not start

systemctl status tuxchange
journalctl -u tuxchange -n 50

The usual cause is the wireless interface. With SP_IFACE empty, only an ath9k adapter is picked, and with none present the service keeps retrying without touching your other adapters. A named adapter that has gone missing falls back to an ath9k card if there is one. Interface names can change between reboots, so check the name if you set one.

The GUI cannot start the service

Interactive authentication required means the polkit rule is not in place. Re-run sudo ./install/install.sh install from a desktop session so $SUDO_USER is set, or run a polkit agent.

The GUI or ctl gets "permission denied" on the socket

The control socket is open only to root and the user who ran the installer. Use that account, use sudo, or re-run sudo ./install/install.sh install from the account that should have access.

The radio is frozen

sudo ./scripts/sp_monitor.sh down
sudo ./scripts/sp_monitor.sh up

Restarting the service does the same thing (ExecStartPre rebuilds the interface every time). The unit also has a 120-second watchdog.

A key error

The message names the value, the file, every path searched, and the command that produces it. Follow it, and see Getting your keys.

Clone this wiki locally