Troubleshooting

Troubleshooting

Every symptom below is paired with the exact string the program prints (captured from the studied build during this wiki's verification run, or quoted from source where a path was not reachable under Wine) and with the code path that produces it. Exit codes follow the contract 0 ok · 1 invalid arguments · 2 unsupported OS/store · 3 partial failure.

---

Contents

• Reading exit codes
• Store and OS problems
• Icons hid again / the guard seems idle
• Silent failures and how to detect them
• Update problems
• Launch, window and tray behavior
• SmartScreen, MOTW and antivirus
• Side-by-side configuration error
• Logs, diagnostics and reset
• Wine, VMs and glyph boxes
• See also

---

Reading exit codes

Code	Meaning	Typical producers
0	success	everything that completed
1	invalid arguments	unknown flag (printed message: none — see silent failures)
2	unsupported OS/store	--promote-all, --restore-defaults, --watch on pre-1703 or absent store
3	partial failure	IPC with no running instance, backup/restore errors, Explorer restart failure, update failures

Store and OS problems

“error: NotifyIconSettings store not supported on this Windows build” — --promote-all on a machine without HKCU\Control Panel\NotifyIconSettings (pre-1703, or a redirected corporate hive). Exit 2. Confirm with --status --json → "storeSupported": false. The Dashboard shows the same fact as a hero card: “Not supported on this Windows build”, with the System card explaining “Unavailable (build < 15063)”.

--restore-defaults / --watch exit 2 with no output — same condition, but these two verbs return before printing anything. If your scripts see a bare exit 2, run --status --json to distinguish “unsupported store” from other causes.

Icons exist but the list is empty — the store key exists yet no application has registered an icon this session (fresh profile, or all tray apps run under another user). reg query "HKCU\Control Panel\NotifyIconSettings" shows the subkeys the app enumerates; the BAT-era findstr /b HKEY_ trick in Legacy Script Editions explains why the root key's own values must not be counted.

Icons hid again / the guard seems idle

Decision tree, in order:

1. Is the guard running? Status bar shows Guard: off / paused / running; tray dot is green when running, amber when paused. Resume from Dashboard, tray menu, or --toggle-guard.
2. Published 8.3.0/8.4.0 build with pollMs: 0? Then the reconcile loop never wakes by itself (armed registry event not waited on — The Guard Watcher). Set Guard → Polling fallback to 2/5/15 s, or deploy the patched build from this wiki's fix bundle. Symptom signature: Guard statistics show passes stuck at 0 while the dot is green.
3. Windows 11 24H2+ layout caching? Some builds keep the old tray layout until the shell refreshes: press Restart Explorer once, or enable Auto-restart Explorer with a cooldown.
4. Exclusions or user-hidden intent? Filters Excluded / Hidden on the Icons page show which rule applies; remove the wildcard or un-hide the row.
5. Check the Activity page / log for EVENT promoted … lines (passes that ran) versus silence (passes that never ran).

Silent failures and how to detect them

Invocation	Observed behavior	Detection
any unknown flag, e.g. --bogus	exit 1, no output; a running GUI instance is also told to show its window	wrap invocations: non-zero + empty stdout ⇒ argument error
--restore-defaults, --watch on absent store	exit 2, no output	pair with --status --json
--show / --toggle-guard with no GUI	exit 3, no output	expected; treat 3 as “no instance”

The parser builds an unknown argument: … message internally, but wWinMain discards it (src/main.cpp) — one of the defects recorded in Changelog and Versioning and fixed in the shipped fix bundle (the patched build prints the message plus a usage hint).

Update problems

All strings below come from src/core/cli.cpp / src/core/update.cpp / the About page:

Message	Cause	Fix
update check failed: HTTP 404	feed missing on the default branch	check update/stable.json location
update check failed: only https (or loopback http for tests) feeds are allowed	non-loopback http feedUrl	use https or 127.0.0.1/localhost
update check failed: bad feed JSON: …	malformed feed	fix the JSON; the check falls back to the releases probe for novelty only
sha256 mismatch (feed=… file=…)	served bytes differ from the pin	republish feed with the hash of the served bytes
download failed: … / cannot create destination file	network/disk/AV	retry; check %TEMP% writability
cannot rename running exe (…)	AV/EDR lock	retry; exclude the folder
already up to date (8.4.0) while you expected newer	running build already at feed version	expected
feed says newer forever on a self-built binary	self-built 8.3.0 vs feed 8.4.0 (version drift)	expected until you bump sources or install the release; see Self-Updater Guide caveat

Launch, window and tray behavior

Window does not appear, only the tray icon — by design: the close button minimizes to tray. Double-click the shield, or hold Shift while closing to exit, or set "behavior": {"closeToTray": false}.

Second launch seems to do nothing — single-instance: the second process forwards show to the first and exits 0. Use --show explicitly from scripts.

Nothing on screen after login autostart — autostart passes --minimized; the app lives in the tray. If the tray icon is also missing after an Explorer crash/replacement, the TaskbarCreated handler re-adds it on real Windows; on shell replacements that never send the message, open the window once via --show.

Dark title bar missing on old Windows 10 — DWMWA_USE_IMMERSIVE_DARK_MODE needs 1809+; earlier builds keep a light frame with a themed client area.

Settings edits ignored — the loader clamps: debounceMs into 50–5000, pollMs ≥ 0, explorerCooldownSec ≥ 10, theme into 0–2; unknown keys are ignored by design.

SmartScreen, MOTW and antivirus

Unsigned community binary + Mark-of-the-Web = one SmartScreen prompt on first launch of a downloaded copy. Preferred fixes, in order: install through the first-run wizard (the CopyFileW copy is MOTW-free), Unblock-File the portable copy, or sign it yourself and re-hash the feed. Generic AV heuristics on static mingw binaries are known; the write scope is small and documented (Security and Privacy), and building from source is the ultimate review.

Side-by-side configuration error

“The application has failed to start because its side-by-side configuration is incorrect.” — official builds since 8.2.1 embed a canonical manifest; earlier 8.x manifests (duplicate supportedOS GUID, non-canonical windowsSettings) could be rejected by strict Windows 11 SxS validation while lenient parsers accepted them. If you still see it: run 8.2.1+; avoid parent folders whose name ends in .exe; unpack with standard tools; capture sxstrace.exe -logfile:sxs.log for a report.

Logs, diagnostics and reset

What	Where
Daily log (14-day rotation)	%LOCALAPPDATA%\TrayIconGuard\logs\TrayIconGuard-yyyyMMdd.log
In-memory ring (500)	Activity page
Settings	%APPDATA%\TrayIconGuard\settings.json
Snapshots	%LOCALAPPDATA%\TrayIconGuard\backups\
Clipboard report	About → Copy diagnostics (OS, theme, language, paths, last 25 log lines)

Log line shape, verbatim sample from the verification run:

2026-10-16 00:17:33.855 [INFO ] === TrayIconGuard 8.3.0 starting ===
2026-10-16 00:17:33.935 [WARN ] guard cannot start: NotifyIconSettings store absent

Full reset: exit the app, delete both AppData folders, run TrayIconGuard.exe --restore-defaults to hand promotion back to Windows.

Wine, VMs and glyph boxes

Under Wine and stripped VMs: the store is absent (no NotifyIconSettings), so store verbs exit 2/3 and the Dashboard shows the unsupported card — expected, not a bug. Navigation and page glyphs render as boxes because Segoe Fluent Icons / MDL2 Assets fonts do not exist there; layout, colors and text remain correct. --status on Wine reports the Wine build number with a Windows 10 caption (the caption logic labels anything below build 22000 as Windows 10), which is honest but can confuse: judge storeSupported, not the caption.

---

See also

• Command-Line Interface — the full verb and exit-code table
• The Guard Watcher — the idle-watcher defect and its fix
• Self-Updater Guide — update failure matrix in publication context
• Security and Privacy — signing, MOTW and trust boundaries