Skip to content

Troubleshooting

Ö. Efe D. edited this page Sep 16, 2026 · 2 revisions

Troubleshooting

Collecting information

Start tron with debug logs and include them in a bug report:

RUST_LOG=debug tron 2> tron.log

Also include tron --version, your distribution or macOS version, your GPU, and on Linux whether you use Wayland or X11.

'xterm-tron': unknown terminal type

A program does not know tron's terminfo entry.

  • On a remote host: see Remote Hosts. ssh sessions are handled automatically; docker exec, sudo and similar tools need the entry copied.
  • Locally: install tic (package ncurses on Fedora, ncurses-bin on Debian and Ubuntu) and restart tron.
  • Quick fix anywhere: set term = "xterm-256color" under [shell].

tron is not in the application menu or search

  • Install with the Installation script; it installs the desktop entry and refreshes the caches.
  • On KDE Plasma, run kbuildsycoca6 if tron still does not show up. On GNOME, log out and back in.
  • Check that ~/.local/share/applications/dev.tron.Terminal.desktop exists.

The window shows the wrong icon or groups oddly in the task bar

The task bar matches windows to the desktop entry dev.tron.Terminal.desktop by app id. Install the desktop entry with the install script. After an upgrade from an old version, remove task bar entries you pinned under the old name and pin tron again.

A shader does nothing or shows an error

  • Check the file name in [shader] files, including the .wgsl extension.
  • Compile errors show in the window for 15 seconds and in the log. Line numbers count the prelude tron adds before your shader.
  • Animated shaders need tron.time or tron.frame, or animation = "always". See Writing Shaders.
  • Shaders that look for dark pixels, like smoke-and-ghost.wgsl, need a black or very dark background.

Text looks blurry or too thin

  • Try hinting = "on" or "off" under [font]. auto hints only below 1.5x display scale.
  • Make sure the font is a real monospace font: fc-match monospace shows what monospace resolves to on Linux.

Missing glyphs or boxes instead of icons

Add a font with the symbols to fallback under [font]:

[font]
fallback = ["Symbols Nerd Font Mono", "Noto Color Emoji"]

Box drawing and Powerline glyphs never need a font; tron draws them.

The cursor stays a block after Neovim exits in tmux

tmux resets the cursor of terminals named xterm-* to a steady block, whatever the terminfo entry says, so a beam or underline cursor set under [cursor] turned into a block after a program such as Neovim reset it. tron puts a tmux wrapper first in the shell's PATH. Before tmux attaches the window, it sets this override, so resets give back the configured cursor:

set -as terminal-overrides ',xterm-tron:Se=\E[0 q'

tmux reads overrides only when a client attaches. Detach and attach again from a tron shell once after upgrading. For tmux started outside tron's shell, such as on a remote host, add the line to ~/.tmux.conf.

Icons show as underscores in tmux

tmux replaces characters outside ASCII when the locale is not UTF-8. Apps started from the macOS Finder or Dock get no locale, so tron sets LANG for its programs when LANG, LC_ALL and LC_CTYPE are all unset: the macOS locale with .UTF-8 when it is installed, else en_US.UTF-8, and C.UTF-8 on Linux. A locale you set is left alone. If you still see underscores, check locale in the shell and restart the tmux server, which keeps the locale it started with.

A new shell starts in the home directory

Shells start in the directory you asked for while it exists, else in the directory tron started in. When that directory is gone, such as on a disk image that was ejected, inside tron's own app bundle, or / as when tron starts from a macOS launcher, the shell starts in the home directory instead.

Clipboard does not work in tmux or over ssh

Programs set the clipboard with OSC 52. osc52 = "copy", the default, allows that. In tmux, also set set -g set-clipboard on.

Copy and paste keys

On Linux, copy and paste are Ctrl+Shift+C and Ctrl+Shift+V, because Ctrl+C interrupts programs. Selecting text also copies it to the primary selection for middle click paste.

Notifications do not show

  • On Linux, install notify-send (package libnotify or libnotify-bin).
  • The default mode = "unfocused" shows notifications only while tron has no focus. Use mode = "always" to test.

Slow start or high GPU use

  • Background shaders that read tron.time redraw every frame. Use cursor shaders, which idle, or animation = "never".
  • The first start after an upgrade compiles shader pipelines; later starts load them from ~/.cache/tron.

Reporting a bug

Open an issue with the log, your versions and the steps that show the problem. For rendering bugs, a screenshot helps: TRON_SCREENSHOT=/tmp/tron.png tron.

Clone this wiki locally