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 configured SSH terminals, check host, user, port, and key. Password fields require sshpass and are less safe than key-based authentication.

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

postconnect=tmux new-session -A -s production

A Template Does Not Load

Check that:

• The system configuration path is the one selected by $SUPERTERM_INI.
• Terminal sections begin with t.
• Referenced terminal names exist and are enabled.
• Template, session, window, and pane names match exactly.
• A SQLite directory is resolved relative to the configuration file.

Enable diagnostics when needed:

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

Do not put passwords in the log or command line.

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.