Troubleshooting

Troubleshooting

Common symptoms and fixes. If your problem isn't listed here, please open an issue.

---

Installation issues

Config not loading after cloning

Symptom: WezTerm starts with default (stock) appearance.

Possible causes:

1. Wrong clone path. WezTerm looks for its config in ~/.config/wezterm/ (Linux/macOS) or %USERPROFILE%/.config/wezterm/ (Windows). Make sure the wezterm.lua file is directly inside that directory, not nested in a subfolder.

   # Verify the file exists:
   ls ~/.config/wezterm/wezterm.lua     # Linux/macOS

   # Windows:
   Test-Path $env:USERPROFILE/.config/wezterm/wezterm.lua

2. Using stable WezTerm instead of nightly. This config requires WezTerm nightly builds. Some APIs used (like config_builder, InputSelector improvements, and format-tab-title) are not available in the stable release. Install from: wezfurlong.org/wezterm/installation

3. Missing fonts. WezTerm will start without the required fonts, but the terminal may look wrong. Install:

   • Fira Code NerdFont
   • Monaspace Radon
   • Monaspace Argon
   • Monaspace Krypton

Git clone fails on Windows

Symptom: git clone fails or clones to the wrong path.

Ensure you're using the correct path syntax for your shell:

# PowerShell (v5 or v7):
git clone https://github.com/sravioli/wezterm.git "$env:USERPROFILE/.config/wezterm"

:: CMD:
git clone https://github.com/sravioli/wezterm.git "%USERPROFILE%/.config/wezterm"

---

Status bar issues

Status bar not showing

Symptom: no status bar elements are visible.

1. Check whether the status bar is enabled.

   Look at opts/statusbar.lua - the enabled field should be true. If you're using overrides, check overrides/opts/init.lua (it must mirror the opts/ structure) for any statusbar.enabled = false setting.

2. Check whether the update-status event is enabled.

   Look at opts/events.lua - update_status should have enabled = true.

Status bar elements are cut off or missing

Symptom: some right-side elements (battery, clock, hostname) don't appear or are truncated.

This is expected. The status bar uses a budget-aware rendering system with fallback modes:

full  -->  trim  -->  text  -->  icon  -->  (hidden)

When your terminal is too narrow to fit all elements at their full width, they progressively degrade. To see all elements, widen your terminal window.

If you want to reduce the number of elements shown (to give remaining ones more space), customize the layout:

-- overrides/opts/statusbar.lua
return {
  statusbar = {
    layout = {
      right = { "cwd", "clock" },  -- Removed hostname and battery
    },
  },
}

Battery not showing on desktop

Symptom: the battery element never appears, even when the terminal is wide.

On desktop machines without a battery, WezTerm's wezterm.battery_info() returns an empty table. The battery module handles this gracefully by not rendering. This is expected.

---

Modal prompt issues

Prompts not visible or truncated

Symptom: after entering a mode (for example, <leader>w), the mode label shows but the key hints don't appear or are partially cut off.

The hint system paginates prompts to fit the available width. If your terminal is very narrow, hints may not fit even on the first page. Try:

1. Widen your terminal. Prompts need space to render.
2. Navigate hint pages. Use <C-S-A-Left> / <C-S-A-Right> (hidden bindings) to page through available hints.

Mode indicator shows but wrong color

Symptom: mode colors look off or are all the same.

Mode colors are derived from the active colorscheme's ansi and brights arrays. If you're using a custom colorscheme with unusual color values, the mode indicators may not look as expected. Each mode uses a specific index:

Mode	Color source
Help	ansi[5]
Window	ansi[6]
Font	ansi[7]
Copy	brights[3]
Search	brights[4]
Lantern	ansi[2]

---

Font issues

Custom font not appearing in Lantern

Symptom: you added a font flame, but it does not show in the selector.

1. The file must return the correct structure. Ensure your file exports both glow() and ignite() functions. See Customization - Adding a font preset.

2. The file must have a .lua extension. Folder-backed Lantern wicks scan for *.lua files only.

3. The font must be installed on the system. WezTerm can only use fonts that are installed in your operating system's font directory.

4. Restart WezTerm or press <C-S-r> to reload the config. Lantern flame directory scans are cached; you can also clear the cache from the command palette (<C-S-p> -> "Invalidate cache").

Font rendering looks wrong after switching

Symptom: after picking a new font, some glyphs look off, or bold/italic styles don't work correctly.

The default config/font.lua includes specific font_rules for Monaspace variants (italic, bold, bold-italic). When you switch to a different font via Lantern, those rules may conflict. Most font flames clear the font_rules table

• check your flame's ignite() function. The built-in reset flame restores the default font configuration.

---

Performance issues

Terminal feels slow or laggy

1. Check the logging level. Debug-level logging adds overhead. In opts/utils/config.lua, ensure the threshold is at least "INFO":

   log = { enabled = true, threshold = "INFO" }

   Or disable logging entirely:

   log = { enabled = false }

2. Try another GPU backend. If you experience rendering issues, switch the GPU backend. Create overrides/config/init.lua:

   -- overrides/config/init.lua
   return {
     front_end = "OpenGL",  -- Try "OpenGL" if "WebGpu" has issues
   }

3. Clear caches. If memoized values become stale (for example, after changing colorschemes repeatedly), use the command palette (<C-S-p>) and select "Invalidate cache" to clear all cached data.

---

WSL / SSH issues

WSL domain not connecting

Symptom: Ubuntu or Alpine WSL domains don't appear or fail to connect.

1. WSL must be installed and running. Verify with wsl --list --verbose.

2. The default user must match. The WSL domains in config/general.lua are configured for user sravioli. If your WSL username is different, override it:

   -- overrides/config/init.lua
   return {
     wsl_domains = {
       { name = "WSL:Ubuntu", distribution = "Ubuntu", username = "your-user" },
     },
   }

3. The distribution name must match exactly. Run wsl --list to see the exact name of your installed distributions.

See Platform Setup - Windows for more details.