Troubleshooting

A pane restored to the wrong directory

Almost always a PowerShell pane without the shell snippet. PowerShell’s process working directory never changes when you change directory — Set-Location updates the provider location, not the process — so there is nothing for WinMux to read.

Settings → Working directories → Set up…, then restart the pane. The status bar’s left segment will start saying shell-reported instead of where it was launched.

WSL panes are the same story and cannot be fixed any other way: reading the process gives a Windows path for a Linux shell, so WinMux refuses to use it rather than confidently restoring somewhere wrong.

An application will not go into a pane

It is elevated. A non-elevated process cannot manipulate an elevated application’s windows. WinMux says so in plain words, and will not ship elevated to work around it — that would be a worse trade than the inconvenience.

It is a packaged or UWP application. Those refuse differently and fall back to attach mode automatically.

It refuses for its own reasons. WinMux falls back to attach mode and says why. Ctrl+B a switches back and forth at any time.

Usually one of two SMB defaults that modern Windows tightened: signing is required, and guest access is refused. Both are checked with one command, and both have a proper fix on the server side.

A cmd pane that keeps restoring to C:\Windows instead of a share is a third, separate problem: cmd.exe cannot start in a UNC directory at all and says so on a line nobody reads.

See Network shares for all three.

WinMux closed on its own

Every unhandled exception is written to %LOCALAPPDATA%\WinMux\crash.log, with the time, the process id, the WinMux version and the full stack. An ordinary exit writes a line there too, so a crash and a close can be told apart afterwards:

2026-09-24 05:41:32.384 +02:00  process exit, code 0  pid 39772  version 0.7.3
2026-09-24 05:42:46.514 +02:00  unhandled exception on the UI thread  pid 30228  version 0.7.4

Two things to know before you go looking:

Copy it before you carry on using WinMux. The file is capped at 1 MB and is deleted, not rotated, on the next write past that.
An empty log is informative too. The handlers catch managed exceptions; a stack overflow, an access violation in native code or a FailFast bypasses them and leaves nothing. If the crash is not in the log, look in Event Viewer under Windows Logs -> Application for a .NET Runtime or Application Error entry naming WinMux.exe.

If it is reproducible, WINMUX_DEBUG_PTY=1 captures the pane’s raw output for replay, and WINMUX_DEBUG_KEYS=1 records what each key became. The key log contains everything typed into a pane, passwords included — turn it on deliberately and delete it afterwards.

A crash log is the most useful thing you can attach to an issue.

The chrome looks wrong

If Mica is unavailable, WinMux says so in the status bar on startup and uses an opaque window. That is a system capability, not a setting.

A provider did not load

The status bar says why. See Writing a pane provider for the full list — the most common cause is an assembly in a directory that is not named after it.

The update did not install

WinMux refuses to install an archive whose SHA-256 is not in the release’s checksums.txt, or when the release published no manifest at all. That is deliberate. Download it by hand from the releases page if you want to proceed anyway.

Known limits

Snap layouts work because WinMux claims its own maximise button. Aero Snap by dragging and the Win+arrow keys are the system’s and always work regardless.

Restoring does not restore process state. Scrollback, running jobs and full-screen program state are gone on restart. Nothing can bring them back, and WinMux says so rather than letting you find out.