Troubleshoot workspace loading

Edit this page on GitHub

tmuxp 1.74.0 · Source

This page documents the available Python tmuxp reference. Proposed native extensions are labeled separately.

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 filesLink to section

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 commandsLink to section

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 stateLink to section

$ 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.

Native failures must be evaluated against port compatibility, not inferred from a Python example. The proposed machine contract reports completed and failed stages explicitly.

tmuxp reference source.