# Troubleshooting VxSound

1. Open **Settings → Audio System** and enable **Enable detailed debug logging for this session**.
2. Repeat the action that fails. Note what you expected, what happened, and the approximate time.
3. Click **Export Debug Bundle** and choose where to save the ZIP.
4. Review the ZIP before sharing it with a bug report. Include reproduction steps and whether restarting VxSound helps.

Debug mode resets when VxSound closes. To capture startup diagnostics, fully exit VxSound (including the tray), then launch `VxSound.exe --debug`.

**Open Log Folder** opens `%LOCALAPPDATA%\VxSound`. The app keeps category logs plus `diagnostics.log`, with one previous file per category. Entries contain UTC time, severity, random session ID, process/thread IDs, and category. Exceptions include the caller's source filename, line, member, HRESULT and stack trace. Release builds may not provide source lines within exception stack traces.

The audio service writes `%PROGRAMDATA%\VxSound\Logs\audio-service-runtime.log`. Export includes both current and previous service logs when readable. `collection.txt` identifies missing/inaccessible logs. Export reads at most the last 4 MiB of each allowlisted log; it does not collect settings, hearing profiles or audio recordings. App log rotation remains 2 MiB per file and service rotation 4 MiB.

Common user/machine identifiers, profile paths, device instance identifiers, GUIDs, IPv4 addresses, email addresses and labeled credentials are masked during export, including older logs. Redaction is best-effort: device/application names and arbitrary error text may still contain personal information. Nothing is uploaded automatically. The random session ID is retained to correlate errors across files.

If the app closes unexpectedly, the error dialog includes the session ID and log folder. Restart and export the bundle before reproducing many more events, which could rotate out older logs. A hard process kill, power loss, native crash, or an unwritable log directory can prevent the last event from being recorded.

For developers: use `DiagnosticsLog.Write(exception)` for failures, `Warning` for degraded state, category methods for lifecycle events, and `Debug` for optional detail. Do not log audio samples, secrets, or every audio callback. Logging currently writes synchronously: keep it out of real-time processing loops.

## Updates fail or appear stuck at 100%

v0.2.18 closes the checksum reader before renaming the verified download, fixing the Windows sharing violation in older updaters. Fully exit the old app and run the latest Setup manually once to obtain the fix. Check the startup version in `ui.log` or Settings afterward; a 100% download does not mean the new version was installed.

`app-update.log` records release/package selection, download, verification, launch, cancellation and failures. Exceptions also go to `diagnostics.log` with HRESULT and stack trace. Installed/full-ZIP copies download verified Setup; portable copies use the replacement helper. All failed or cancelled attempts preserve any previously verified download and clean only their own partial file.

Debug bundles include current/previous `app-update.log` and the known helper/installer logs `updates/update.log` and `updates/setup.log` when present, using the same bounded reads and redaction. Setup writes its log after accepting the administrator prompt. A manual Setup only writes this log if launched with an explicit `/LOG` argument. Complete Setup before collecting its log. User settings and listening data remain excluded.

## Routing shows "Access to the path is denied"

The desktop app and installed service run under different Windows identities. Older builds created the service's named pipe with the default Windows descriptor, which does not grant ordinary desktop users the write access needed for requests. The pipe now grants local interactive users explicit read/write access, with full control reserved for SYSTEM and Administrators; network and anonymous logons are denied. The client requests individual rights rather than generic write, so desktop users cannot create another instance of the service pipe. See [Microsoft's named-pipe access documentation](https://learn.microsoft.com/en-us/windows/win32/ipc/named-pipe-security-and-access-rights).

Update/reinstall **both** the app and the audio service using the fixed installer, then restart VxSound. Replacing only the app executable leaves the old service running with its old pipe permissions. Connection-denied logs identify the IPC stage and HRESULT. Current App Routing views read desktop sessions directly; service connection failures still affect service-backed features. Client disconnects and stalled requests no longer end the pipe listener.

This is separate from virtual endpoint availability: VxSound currently does not bundle its own signed virtual audio driver. Live separated channels need compatible virtual playback endpoints (one per independent channel) assigned in the mixer, plus your physical headset as output. Preview files, built-in test sounds and hearing tests do not require virtual cables. Installing a cable alone does not repair service permissions or automatically assign channel inputs.

## Empty app list, missing cables or settings reset

App Routing and Routing Board now use the desktop user's audio sessions and Sound Studio cable assignments. Start playback in an app, then refresh sessions. A cable must be selected for the channel, active, used by only one channel, and configured for mono or stereo. Select your real headset as the physical output and start the live mixer.

`app-routing.log` records the Windows session number, device/session counts, cable availability, saved explicit choices and failures. Detailed debug mode adds per-app session information and enumeration errors. Routing logs are included in diagnostic bundles; saved rules and settings are excluded.

Earlier startup checks incorrectly rejected schema-v2 settings and the four-channel layout, causing valid files to be renamed to `settings.invalid-*.json` or ignored. Current builds use one settings validator, preserve all four channels, and migrate older three-channel files by adding an unassigned Aux channel. Valid current settings are no longer quarantined. Existing backup files are not automatically restored over newer settings.