Troubleshooting#

Review logs/error messages#

If things aren't working out, there may be an issue printed in the logs. Read on to learn more about how to see those logs.

Debug Overlay#

By default, pressing Ctrl + Shift + L will activate the debug overlay and allow you to review the most recently logged issues. It also gives you access to a Lua REPL for evaluating built-in lua functions.

See ShowDebugOverlay for more information on this key assignment.

Log Files#

You can find log files in $XDG_RUNTIME_DIR/wakterm on unix systems, or $HOME/.local/share/wakterm on macOS and Windows systems.

Increasing Log Verbosity#

The WAKTERM_LOG environment variable can be used to adjust the level of logging for different modules within wakterm.

To see maximum verbosity, you can start wakterm like this:

WAKTERM_LOG=debug wakterm

to see debug level logs for everything on stdout.

On Windows systems you'll usually need to set the environment variable separately:

Using cmd.exe:

C:\> set WAKTERM_LOG=debug
C:\> wakterm

Using powershell:

PS C:\> $env:WAKTERM_LOG="debug"
PS C:\> wakterm

When using a flatpak you must first enter the flatpak container by running:

flatpak run --command=sh --devel org.wezfurlong.wakterm

Before then running wakterm.

Each log line will include the module name, which is a colon separated namespace; in the output below the modules are config, wakterm_gui::frontend, wakterm_font::ftwrap and wakterm_gui::termwindow:

10:29:24.451  DEBUG  config                    > Reloaded configuration! generation=2
10:29:24.452  DEBUG  wakterm_gui::frontend     > workspace is default, fixup windows
10:29:24.459  DEBUG  wakterm_font::ftwrap      > set_char_size computing 12 dpi=124 (pixel height=20.666666666666668)
10:29:24.461  DEBUG  wakterm_font::ftwrap      > set_char_size computing 12 dpi=124 (pixel height=20.666666666666668)
10:29:24.494  DEBUG  wakterm_gui::termwindow   > FocusChanged(true)
10:29:24.495  DEBUG  wakterm_gui::termwindow   > FocusChanged(false)

Those modules generally match up to directories and file names within the wakterm source code, or to external modules that wakterm depends upon.

You can set a more restrictive filter to focus in on just the things you want. For example, if you wanted to debug only configuration related things you might set:

WAKTERM_LOG=config=debug,info

which says:

log config at debug level
everything else at info level

You can add more comma-separated items:

WAKTERM_LOG=config=debug,wakterm_font=debug,info

See Rust's env_logger documentation for more details on the syntax/possibilities.

Turn on debug_key_events to log information about key presses.

Use wakterm show-keys or wakterm show-keys --lua to show the effective set of key and mouse assignments defined by your config.

Consider changing use_ime to see that is influencing your keyboard usage.

Double check to see if you have some system level utility/software that might be intercepting or changing the behavior of a keyboard shortcut that you're trying to use.

Debugging Font Display#

Use wakterm ls-fonts to explain which fonts will be used for different styles of text.

Use wakterm ls-fonts --list-system to get a list of fonts available on your system, in a form that you can use in your config file.

Use wakterm ls-fonts --text foo to explain how wakterm will render the text foo, and wakterm ls-fonts --text foo --rasterize-ascii to show an ascii art rendition of that text.

Troubleshooting