Troubleshooting

Troubleshooting

It will not connect

First: do not trust ping. This console drops ICMP but accepts TCP. A failed ping tells you nothing. Probe the port instead:

nc -z -G 4 <console-ip> 6060 && echo up || echo down

Symptom	Cause
Connection refused	The agent is not running. Check flags/boot2.flag exists and the contents path is exactly atmosphere/contents/420000000000AE57/.
Connection times out	Console asleep, or its IP changed. The Wi-Fi radio is off in sleep — nothing can reach it until it wakes.
auth error	SWITCH_TOKEN does not match token in config.ini.
Worked, then stopped	Wi-Fi power-save. The first connect after an idle period can take several seconds; the client allows 15 s.

If the IP changed, use find_console or the discovery scan in Installation.

The console keeps disappearing

The lockscreen sleeps even with auto-sleep set to Never, and sleeping tears down the network. That is why the agent clears the lockscreen itself 12 s after boot and nudges every 10 minutes while no game is running.

If it is still happening, check clear_lockscreen_on_boot = true and keep_awake_minutes in config.ini, and note that both are skipped at observe tier — injecting input is a control-tier action, so a read-only agent will still let the console strand itself.

A command is refused

Read the error; it names what to change.

Error	Meaning
tier_denied	The command needs a higher tier. No other tool call will work around it — edit config.ini and restart.
disabled	A sub-gate blocks it (allow_nand_write, allow_hardware, allow_overclock), even at invasive.
read_only_device	You passed device="save" to a write command. Save mounts are read-only by construction.
unknown_command	The agent build is older than the server. Call capabilities for what it actually supports.
uncertain	The command reached the console but the reply was lost. It may or may not have taken effect — check state before re-issuing. It was deliberately not retried.

capabilities() shows the tier and the exact permitted command list.

Nothing in the agent log — or no log at all

This is the important failure mode. If sd:/config/switch-agentd/agent.log has no entry for the current boot, the sysmodule is not starting, and it died before logging was up. There will be no crash report either.

Recover by holding Volume-Up during boot to skip boot2 sysmodules, then replace or delete atmosphere/contents/420000000000AE57/.

Known causes, all fixed in current builds but worth recognising if you are modifying the agent:

• A large stack buffer. The main thread stack is 64 KiB; GCC reserves the whole frame in the prologue, so a big local array kills the module on function entry, before any of its code runs.
• Raising INNER_HEAP_SIZE past 4 MiB. A sysmodule's heap comes from a constrained system pool, not free RAM. The allocation fails during init and the module dies silently. There is a static_assert against this now.

Black screen, console unresponsive

Hold Power for ~15 seconds to force it off, then power on normally. Nothing is damaged.

The known cause is a power-state (psc) module that fails to acknowledge a sleep request — the system waits for it forever. enable_psc is off by default for exactly this reason. If you turned it on, turn it back off.

Homebrew will not start

Check for a stale hbloader process:

list_processes()      # look for 0142b048fd620000 while the home menu is showing
terminate_title()     # clears the stale application slot

When homebrew crashes, its slot is sometimes left occupied, and anything launched afterwards fails. Note also that launch_title cannot start homebrew — use the Album applet.

A debugger command fails

Error	Meaning
not_attached	Call debug_attach first.
ctx_failed on a write	Register writes need the thread stopped at a debug event — a paused attach is not enough.
ctx_failed on a read	You attached with pause=false. Reads need a paused attach.
hw_bp_failed	Expected. See below.

Hardware watchpoints and breakpoints do not fire. Arming, all three modes, slot bounds and clearing all work, but no exception is ever delivered on HOS 22.1.0. Core affinity was tested as a cause and ruled out. Use the narrowing memory search (find_value / narrow_search) instead — that is verified working.

Everything is slow

Measured on Wi-Fi: 2.8 MB/s up, 4.1 MB/s down, 22.8 ms round-trip. The bottleneck is the link, not the protocol — latency accounts for only ~9% of a 4 MiB transfer, so there is little to tune.

Reduce what you transfer instead: capture_screen(scale=0.25), screen_changed rather than repeated screenshots, and fs_find / fs_grep so searching happens on the console.

Two clients at once

Only one works. Not one command at a time — one session: the agent does not accept a new connection while a client holds one, so the second blocks until the first disconnects. A long wait_event blocks everything, including other sessions.