Troubleshooting

Troubleshooting

fpc or FreeVision Units Are Missing

Install Free Pascal 3.2.2 or a compatible Free Pascal 3.x release, including the FV, FCL, and DB units. Run:

./configure
make info

The project-local vendor/fv322 directory must be available and is placed before system FreeVision units by the build scripts.

The Binary Is Missing

Build it explicitly:

make release

The output is bin/superterm. bin/ and build/ are generated and are not tracked by Git.

Tests Cannot Import pyte

Install the Python dependency for the interpreter selected by configure:

python3 -m pip install pyte

Then rerun:

make test

SSH Pane Does Not Connect

Verify the command outside superterm first. Prefer a key or agent:

ssh -tt alice@host

For a structured SSH window class, check host, user, port, and key. Password fields require sshpass and are less safe than key-based authentication. A class with connect runs that free command instead and takes precedence over host.

If the remote command should remain attached to a persistent console, use a postconnect such as:

postconnect=tmux new -A -s main

A Window Class Does Not Open

Check that:

• The configuration file is the one selected by $SUPERTERM_INI.
• The class section is [class.NAME] and enabled=1.
• The intended type is derived from the fields: connect -> command class, else host -> SSH class, else local class. The old type= key is ignored.
• Legacy [t-*] sections still load but are migrated to [class.*] on the next save from the class manager.

A Profile Does Not Load

Check that:

• The profile header is [profile.NAME] with enabled=1.
• Every name in windows= has a matching [profile.NAME.window.W], and every name in panes= has a matching [profile.NAME.window.W.pane.P].
• Each pane's class= references an existing, enabled window class (an empty class means an ad-hoc pane using its own overrides).
• layout node count matches the number of panes (L is one pane; V:ratio / H:ratio are splits, ratio 0..1000).
• Legacy [template.*] sections (INI or SQLite) are flattened into profiles; an explicit [profile.*] of the same name wins.

Enable diagnostics when needed:

SUPERTERM_DEBUG=/tmp/superterm-debug.log ./bin/superterm

Do not put passwords in the log or command line.

The Prefix Key Conflicts

The default prefix is Ctrl-Q, chosen so a remote tmux/screen inside a pane keeps Ctrl-B untouched. Change it with [keymap] prefix (ctrl-a..ctrl-z, a letter, or 1..26). The old numeric prefix=2 (Ctrl-B) is migrated to Ctrl-Q automatically; write prefix=ctrl-b to keep Ctrl-B on purpose. Press the prefix twice to send one literal prefix byte to the pane.

Esc Does Nothing or Acts as Alt

A lone Esc now reaches the pane: the custom keyboard driver uses a short timeout instead of holding Esc as an Alt prefix, so single-Esc programs (vi, less) behave normally.

A Remote TUI Shows Odd Glyphs

256-color and truecolor sequences are approximated to the 16-color palette, and modern-CLI glyphs (bullets, spinners, tree branches) are rendered through CP437. Slight substitutions there are expected approximation, not corruption. If dialog or text contrast is poor, switch the palette in Options -> Color palette (color, black-and-white, monochrome).

Terminal Rendering Looks Wrong

Check the terminal type and resize behavior. The mouse suite can be exercised with both the normal terminal type and tmux's terminal type:

python3 test/mouse_test.py
SUPERTERM_TEST_TERM=tmux-256color python3 test/mouse_test.py

The bundled FreeVision overlay contains the wide-screen and mouse behavior required by the project.

Configuration Contains Credentials

Keep ~/.superterm mode 700 when it contains credentials and prefer SSH keys or an SSH agent. Never commit personal configuration files, private keys, or debug logs to the repository.