> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Note>
  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.
</Note>

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:

<CodeGroup>
  ```bash Unix/Linux/macOS theme={null}
  WEZTERM_LOG=debug wezterm
  ```

  ```cmd Windows (cmd.exe) theme={null}
  set WEZTERM_LOG=debug
  wezterm
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:WEZTERM_LOG="debug"
  wezterm
  ```

  ```bash Flatpak theme={null}
  flatpak run --command=sh --devel org.wezfurlong.wezterm
  # Then inside the container:
  WEZTERM_LOG=debug wezterm
  ```
</CodeGroup>

### Targeted Logging

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

```bash theme={null}
# 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:

```lua theme={null}
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:

```bash theme={null}
# 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
```

<Tip>
  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.
</Tip>

### Font Looks Blurry or Wrong Size

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

```lua theme={null}
config.dpi = 144.0  -- Adjust to your display
```

### Ligatures Not Working (or Want to Disable Them)

To disable ligatures:

```lua theme={null}
config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }
```

To troubleshoot ligature rendering:

```bash theme={null}
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:

```bash theme={null}
# Check current locale
locale

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

Set a UTF-8 locale in your shell configuration:

```bash theme={null}
export LANG=en_US.UTF-8
export LC_COLLATE=C  # Optional: for technical users
```

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

### Unicode in tmux Shows Underscores

This is usually a locale issue with tmux:

1. Set LANG before starting tmux:
   ```bash theme={null}
   export LANG=en_US.UTF-8
   tmux
   ```

2. Kill and restart your tmux server after changing locale:
   ```bash theme={null}
   tmux kill-server
   ```

3. Ensure tmux is configured for UTF-8:
   ```tmux theme={null}
   set-option -g default-terminal "screen-256color"
   ```

### zsh Shows Broken Unicode When Pasting

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

```bash theme={null}
# Add to ~/.zshrc
setopt COMBINING_CHARS
```

## Keyboard Issues

### Keys Don't Work or Produce Weird Characters

**Step 1: Enable Debug Logging**

```lua theme={null}
config.debug_key_events = true
```

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

**Step 2: Check Key Bindings**

```bash theme={null}
# 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:

```bash theme={null}
xxd
# Press the problem key, then Enter, then Ctrl+D
```

### Alt/Option Key Issues on macOS

The Option key behavior can be configured:

```lua theme={null}
-- 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`:

```lua theme={null}
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:**

```bash theme={null}
WEZTERM_LOG=window::os::x11::cursor=trace wezterm
# Move mouse over window to see cursor resolution attempts
```

**Solution: Configure XCursor Theme**

```lua theme={null}
config.xcursor_theme = 'Adwaita'  -- or your preferred theme
```

**Or Set Environment Variable:**

```bash theme={null}
export XCURSOR_THEME=Adwaita
export XCURSOR_PATH=~/.local/share/icons:/usr/share/icons
```

<Accordion title="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
</Accordion>

## 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:

```lua theme={null}
config.term = "xterm-256color"  -- This is the default
```

<Warning>
  Changing `TERM` to non-standard values can break key handling in many programs. Only change this if you know what you're doing.
</Warning>

### Neovim: Curly Underlines Don't Work

WezTerm supports curly underlines, but Neovim needs terminfo:

```bash theme={null}
# 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`:

```vim theme={null}
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
```

<Note>
  On Windows, ConPTY strips curly underline sequences. Use `wezterm ssh` or multiplexing to bypass ConPTY when connecting to WSL.
</Note>

## Shell-Specific Issues

### PowerShell: Cursor Keys Don't Work in External Programs

This is a [known PowerShell issue](https://github.com/PowerShell/PowerShell/issues/12268). 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:

```bash theme={null}
# 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**

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

<Note>
  For zsh users, add `-l` flag to source `.zprofile`, or `-i` flag to source `.zshrc`.
</Note>

**Solution 2: Use Full Path**

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

**Solution 3: Set PATH in Config**

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

**Solution 4: Configure launchd** (Advanced)

```bash theme={null}
sudo launchctl config user path /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
```

<Warning>
  Changing the launchd user path can affect all GUI applications. Use with caution.
</Warning>

## Performance Issues

### High CPU or GPU Usage

1. **Disable transparency if not needed:**
   ```lua theme={null}
   config.window_background_opacity = 1.0
   ```

2. **Reduce animation:**
   ```lua theme={null}
   config.animation_fps = 10  -- or 1 to effectively disable
   ```

3. **Check for runaway processes in terminal:**
   ```bash theme={null}
   ps aux | head
   top
   ```

### Slow Rendering with Background Images

Large images consume VRAM and slow rendering:

```bash theme={null}
# Resize image before using
convert wallpaper.jpg -resize 1920x1080 wallpaper-resized.jpg
```

## Getting More Help

<Tip>
  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)
</Tip>

### Useful Diagnostic Commands

```bash theme={null}
# 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](https://github.com/wezterm/wezterm/issues)
2. Search the [WezTerm documentation](https://wezfurlong.org/wezterm/)
3. Open a new issue with diagnostic information