# Troubleshooting

Source: https://libtmux.org/en/powershell/latest/guides/troubleshooting/

> Troubleshooting: LibTmux documentation.

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](https://libtmux.org/en/powershell/latest/guides/getting-started/#install) 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](https://libtmux.org/en/powershell/latest/guides/getting-started/#install-from-source) and import the staged manifests. For local shared-source changes, retain the exact inspected archives described in [review package builds](https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/.github/CONTRIBUTING.md#review-package-builds). |
| A server handle exists, but reads cannot reach tmux | [`New-TmuxServer`](<https://libtmux.org/en/powershell/latest/reference/libtmux-new-tmuxserver/>) constructs a local handle. Use [Connect-TmuxServer](https://libtmux.org/en/powershell/latest/guides/read/) to discover an existing daemon, or [New-TmuxSession](https://libtmux.org/en/powershell/latest/guides/create/) 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](https://libtmux.org/en/powershell/latest/guides/placement/) 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](https://libtmux.org/en/powershell/latest/guides/placement/) and [literal input](https://libtmux.org/en/powershell/latest/guides/input/) describe the uncertain cases. |
| Sent text has no captured output yet | [Sending text](https://libtmux.org/en/powershell/latest/guides/input/) acknowledges input, not program completion. Wait on a cooperative channel or a program-specific result, then [capture](https://libtmux.org/en/powershell/latest/guides/capture/) the pane. A sleep does not establish readiness. |
| A watcher reports dropped events | The [event stream](https://libtmux.org/en/powershell/latest/guides/watch/) 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](https://libtmux.org/en/powershell/latest/reference/libtmux-enter-tmuxsession/) needs a foreground terminal with stdin and must run outside another tmux client. Workspace apply is detached; pass its successful native [`Session`](<https://libtmux.org/en/csharp/latest/reference/libtmux-session/>) to the attach command in a terminal. |
| Workspace apply stops partway through | Inspect the native [`WorkspaceBuildException`][workspacebuildexception] journal and partial result described in the [workspace guide](https://libtmux.org/en/powershell/latest/workspace/source-guide/#startup-host-effects-and-failures). 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](https://libtmux.org/en/powershell/latest/guides/mcp/) 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](https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/.github/CONTRIBUTING.md#testing-tmux-behavior) runs
integration checks on owned sockets without touching your default server.

[workspacebuildexception]: https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspacebuildexception/