Troubleshooting
Start with the endpoint and operation that failed. The cmdlets keep native
objects and errors, so an empty result, a failed tmux command and a cancelled
wait have different meanings. Use -ErrorAction Stop when one failure should
stop a script.
| Symptom | Check and next action |
|---|---|
Import-Module LibTmux cannot find a dependency¶ | Follow installation to install from PowerShell Gallery with dependency resolution. Install both PowerShell modules at the same version; importing mixed core assemblies is rejected. For a checkout, use the source build and import the staged manifests. For local shared-source changes, retain the exact inspected archives described in review package builds. |
| A server handle exists, but reads cannot reach tmux¶ | New-TmuxServer constructs a local handle. Use Connect-TmuxServer to discover an existing daemon, or New-TmuxSession to create one on that explicit endpoint. Check the selected socket and executable before retrying. |
| A command targets the wrong session or window¶ | Read the object from the intended server and session. Window placements carry a session-relative index; a physical window can be linked more than once. Raw tmux targets are strings and do not inherit a captured placement guard. |
| A move, input or raw mutation failed after dispatch¶ | Read current topology or screen state before deciding whether to retry. A failed readback or cancelled wait can follow a successful tmux mutation. Placement and literal input describe the uncertain cases. |
| Sent text has no captured output yet¶ | Sending text acknowledges input, not program completion. Wait on a cooperative channel or a program-specific result, then capture the pane. A sleep does not establish readiness. |
| A watcher reports dropped events¶ | The event stream bounds count and text bytes. A loss marker means history is incomplete; acquire a fresh snapshot when current topology matters. Rendered capture is a screen view, not a reconstruction of missed events. |
| Interactive attach fails from a script or CI job¶ | Enter-TmuxSession needs a foreground terminal with stdin and must run outside another tmux client. Workspace apply is detached; pass its successful native Session to the attach command in a terminal. |
| Workspace apply stops partway through¶ | Inspect the native WorkspaceBuildException journal and partial result described in the workspace guide. Review the original plan and live server before another apply; host scripts and sent pane commands are not rolled back. |
| MCP tools or waits are unavailable¶ | The MCP server is an independently installed .NET tool. Check the configured executable, socket and LIBTMUX_TOOLSETS, then initialize the client and read tools/list and tmux://capabilities. A cursor or task from an earlier process is not durable. |
For repeatable failures, record the command, PowerShell and tmux versions, selected socket kind, error ID and original exception. Avoid including pane contents, secrets or private socket paths in a public report. The contributor guide runs integration checks on owned sockets without touching your default server.