Troubleshoot a workspace

tmuxp 1.74.0 · Source

Start by identifying the failing stage. A parser error happens before a workspace is loaded. A missing file is a discovery problem. An accepted document can still fail during tmux creation, shell startup, command dispatch, or a plugin callback.

Arguments and files¶

Use the command reference for local flag meanings. Place root --color and --log-level before the command. Keep multiple load filenames together. Both importer children require a source argument. Confirm an explicit file works before investigating saved-name discovery.

Configuration and commands¶

Check the configuration reference and the example gallery. YAML parsing alone does not validate keys or prove builder support. A missing shell executable, directory, plugin package, SSH target, or application can prevent an otherwise valid workspace from behaving as intended.

Commands are sent into panes and can require shell readiness. enter: false intentionally leaves text unsubmitted. Delays are measured in seconds; explicit zero and omission differ. See commands and hooks.

Diagnostics and remaining state¶

$ tmuxp debug-info --json

Inspect raw tmux values before sharing diagnostics. Use the same -L or -S endpoint when inspecting a failed load. A partial build can leave sessions, windows, and panes behind; inspect them before cleanup. Do not assume rollback or kill an unrelated default server.

tmuxp reference source.