Troubleshooting

Solutions to common WezTerm issues and debugging techniques

This guide covers common issues you might encounter with WezTerm and how to resolve them.

Debugging and Logs

Debug Overlay

The fastest way to see recent log messages is using the debug overlay:

Press Ctrl+Shift+L (or Cmd+Shift+L on macOS) to activate the debug overlay. This shows recent log messages and provides access to a Lua REPL.

The debug overlay lets you:

• Review recently logged issues
• Evaluate Lua functions interactively
• Test configuration changes without reloading

Log Files Location

Log files are stored in different locations depending on your system:

• Unix systems: $XDG_RUNTIME_DIR/wezterm
• macOS/Windows: $HOME/.local/share/wezterm

Increasing Log Verbosity

To see more detailed logs, use the WEZTERM_LOG environment variable:

Unix/Linux/macOS

WEZTERM_LOG=debug wezterm

Targeted Logging

You can filter logs to specific modules for more focused debugging:

# Debug only configuration loading
WEZTERM_LOG=config=debug,info wezterm

# Debug configuration and fonts
WEZTERM_LOG=config=debug,wezterm_font=debug,info wezterm

Log modules correspond to source code paths. Common modules include:

• config - Configuration loading and parsing
• wezterm_gui::frontend - GUI and window management
• wezterm_font - Font loading and rendering
• wezterm_gui::termwindow - Terminal window behavior

Font Issues

Glyphs Render as Underscores or Question Marks

This typically indicates a font fallback issue or missing glyphs.

Solution 1: Configure Font Fallback

Add fonts that contain the missing glyphs:

local wezterm = require 'wezterm'
local config = {}

config.font = wezterm.font_with_fallback({
  'My Preferred Font',
  'DengXian',  -- Better Chinese glyph coverage
  'Noto Color Emoji',
})

return config

Solution 2: Check Font Installation

Use WezTerm’s font debugging tools:

# List available fonts
wezterm ls-fonts --list-system

# Check how specific text will render
wezterm ls-fonts --text "your text here"

# See ASCII art rendering of text
wezterm ls-fonts --text "foo" --rasterize-ascii

WezTerm automatically includes Nerd Font Symbols and Noto Color Emoji in the default fallback. You don’t need specially patched fonts for powerline or icon support.

Font Looks Blurry or Wrong Size

On X11 systems with high-DPI displays, you may need to override the DPI:

config.dpi = 144.0  -- Adjust to your display

Ligatures Not Working (or Want to Disable Them)

To disable ligatures:

config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }

To troubleshoot ligature rendering:

wezterm ls-fonts --text "!= -> =>" --rasterize-ascii

Unicode and Locale Issues

Unicode Characters Don’t Display Correctly

Problem: Characters appear garbled or show as multiple incorrect glyphs.

Solution: Check your locale settings:

# Check current locale
locale

# List available UTF-8 locales
locale -a | grep -i utf

Set a UTF-8 locale in your shell configuration:

export LANG=en_US.UTF-8
export LC_COLLATE=C  # Optional: for technical users

Locale settings must be correct on both local and remote systems when using SSH or multiplexer connections.

Unicode in tmux Shows Underscores

This is usually a locale issue with tmux:

1. Set LANG before starting tmux:

   export LANG=en_US.UTF-8
   tmux
   

2. Kill and restart your tmux server after changing locale:

   tmux kill-server
   

3. Ensure tmux is configured for UTF-8:

   set-option -g default-terminal "screen-256color"
   

zsh Shows Broken Unicode When Pasting

zsh’s line editor doesn’t support combining characters by default:

# Add to ~/.zshrc
setopt COMBINING_CHARS

Keyboard Issues

Keys Don’t Work or Produce Weird Characters

Step 1: Enable Debug Logging

config.debug_key_events = true

This will log all key presses to help identify the issue.

Step 2: Check Key Bindings

# Show all effective key bindings
wezterm show-keys

# Show in Lua format
wezterm show-keys --lua

Step 3: Test with xxd

To see raw byte sequences:

xxd
# Press the problem key, then Enter, then Ctrl+D

Alt/Option Key Issues on macOS

The Option key behavior can be configured:

-- Use Option as Alt (default)
config.send_composed_key_when_left_alt_is_pressed = false
config.send_composed_key_when_right_alt_is_pressed = false

Caps Lock as Leader Key on Linux

If you’ve remapped Caps Lock using setxkbmap -option caps:none:

config.leader = { key = 'VoidSymbol', mods = '', timeout_milliseconds = 1000 }

Mouse Cursor Issues (X11/Wayland)

Old-School X11 Cursor Appearance

WezTerm tries to load XCursor themes but may fall back to basic X11 cursors.

Enable Debug Logging:

WEZTERM_LOG=window::os::x11::cursor=trace wezterm
# Move mouse over window to see cursor resolution attempts

Solution: Configure XCursor Theme

config.xcursor_theme = 'Adwaita'  -- or your preferred theme

Or Set Environment Variable:

export XCURSOR_THEME=Adwaita
export XCURSOR_PATH=~/.local/share/icons:/usr/share/icons

XCursor Resolution Process

WezTerm resolves cursor themes through these steps:

1. Check xcursor_theme in config
2. X11: Check RESOURCE_MANAGER property on root window
3. Wayland: Check XCURSOR_THEME environment variable
4. Fall back to “default” theme

For icon paths:

1. Check XCURSOR_PATH environment variable
2. Construct path from XDG_DATA_HOME and XDG_DATA_DIRS
3. Use hardcoded fallback paths

Terminal Compatibility Issues

Programs Don’t Recognize Function Keys

Problem: F-keys or other special keys aren’t working in applications.

Solution: The TERM environment variable should be set correctly:

config.term = "xterm-256color"  -- This is the default

Changing TERM to non-standard values can break key handling in many programs. Only change this if you know what you’re doing.

Neovim: Curly Underlines Don’t Work

WezTerm supports curly underlines, but Neovim needs terminfo:

# Install wezterm terminfo
tempfile=$(mktemp) && \
  curl -o $tempfile https://raw.githubusercontent.com/wezterm/wezterm/master/termwiz/data/wezterm.terminfo && \
  tic -x -o ~/.terminfo $tempfile && \
  rm $tempfile

# Launch Neovim with TERM=wezterm
TERM=wezterm nvim

For vim, add to .vimrc:

let &t_Cs = "\e[4:3m"
let &t_Ce = "\e[4:0m"
hi SpellBad guisp=red gui=undercurl guifg=NONE guibg=NONE \
  ctermfg=NONE ctermbg=NONE term=underline cterm=undercurl ctermul=red

On Windows, ConPTY strips curly underline sequences. Use wezterm ssh or multiplexing to bypass ConPTY when connecting to WSL.

Shell-Specific Issues

PowerShell: Cursor Keys Don’t Work in External Programs

This is a known PowerShell issue. PowerShell enables DECCKM mode and doesn’t restore it.

Workaround: This affects all terminal emulators. Consider using a different shell or report the issue to the PowerShell team.

Bash: readline Issues

If you have set convert-meta on in ~/.inputrc:

Problem: Latin-1 and other characters appear broken.

Solution: Disable this setting for UTF-8 environments:

# In ~/.inputrc, comment out or remove:
# set convert-meta on

macOS Specific Issues

WezTerm Can’t Find Programs in PATH

When launched from Finder, WezTerm inherits the minimal macOS PATH.

Solution 1: Spawn via Shell

wezterm.action.SpawnCommandInNewWindow({
  args = {
    os.getenv('SHELL'),
    '-c',
    'nvim ' .. wezterm.shell_quote_arg(wezterm.config_file),
  },
})

For zsh users, add -l flag to source .zprofile, or -i flag to source .zshrc.

Solution 2: Use Full Path

wezterm.action.SpawnCommandInNewWindow({
  args = {
    wezterm.home_dir .. '/.local/bob/nvim-bin/nvim',
    wezterm.config_file,
  },
})

Solution 3: Set PATH in Config

config.set_environment_variables = {
  PATH = wezterm.home_dir .. '/.local/bin:' .. os.getenv('PATH'),
}

Solution 4: Configure launchd (Advanced)

sudo launchctl config user path /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

Changing the launchd user path can affect all GUI applications. Use with caution.

Performance Issues

High CPU or GPU Usage

1. Disable transparency if not needed:

   config.window_background_opacity = 1.0
   

2. Reduce animation:

   config.animation_fps = 10  -- or 1 to effectively disable
   

3. Check for runaway processes in terminal:

   ps aux | head
   top
   

Slow Rendering with Background Images

Large images consume VRAM and slow rendering:

# Resize image before using
convert wallpaper.jpg -resize 1920x1080 wallpaper-resized.jpg

Getting More Help

When reporting issues, include:

• WezTerm version (wezterm --version)
• Operating system and version
• Output of wezterm ls-fonts (for font issues)
• Log output with WEZTERM_LOG=debug
• Your configuration file (or relevant parts)

Useful Diagnostic Commands

# Version information
wezterm --version

# Font debugging
wezterm ls-fonts
wezterm ls-fonts --list-system
wezterm ls-fonts --text "problem text"

# Key binding inspection
wezterm show-keys

# Run with debug logging
WEZTERM_LOG=debug wezterm 2>&1 | tee wezterm-debug.log

Report Issues

If you can’t resolve the issue:

1. Check existing issues on GitHub
2. Search the WezTerm documentation
3. Open a new issue with diagnostic information