Common Errors
Most kitty problems fall into a small number of root causes. This lesson covers each category with symptoms, root cause, and the fix.
For each error, the goal is to understand the root cause — not just copy the fix — so you can solve variations on your own.
Issue: Terminal Unknown / TERM Variable Wrong
Symptom:
$TERM is set to "xterm" or "xterm-256color"
$ env | grep TERM
TERM=xterm-256color
Root cause: Kitty expects TERM=xterm-kitty. Without it, remote applications may not enable true color, italic, or kitty-specific protocol features.
Fix:
# Check current TERM
echo $TERM
# Inside kitty, TERM should be xterm-kitty automatically
# If not, set it in kitty.conf:
echo "term xterm-kitty" >> ~/.config/kitty/kitty.conf
For SSH sessions, the remote host needs the kitty terminfo file:
# From your local machine, transfer terminfo to remote
kitty +kitten ssh user@host
# Or manually:
infocmp -x xterm-kitty | ssh user@host tic -x -
A missing or wrong TERM value is the single most common source of kitty issues on remote machines. Always check this first.
Issue: Font Rendering Problems
Symptom: Special symbols render as small boxes, powerline glyphs missing, or kitty fails to start with "font not found."
Root cause: The configured font is not installed, or the font lacks the required glyphs.
Fix:
# List available fonts kitty can use
kitty --debug-fonts 2>&1 | grep -i "found"
# Check your current font setting
grep -i "^font" ~/.config/kitty/kitty.conf
# Install a recommended font with good Unicode coverage
# On Debian/Ubuntu:
sudo apt install fonts-firacode fonts-powerline
# On Arch:
sudo pacman -S ttf-fira-code
# Recommended settings for font fallback:
font_family Fira Code
bold_font Fira Code
italic_font Fira Code
font_size 12.0
# Add fallback fonts
font_family Noto Mono
Issue: Keyboard Shortcuts Not Working
Symptom: Kitty shortcuts like Ctrl+Shift+Enter do nothing, or the key combination is captured by the window manager.
Root cause: The window manager or desktop environment is intercepting the shortcut before kitty sees it.
Fix:
# Identify the conflict — check if outside kitty the shortcut does something
# Common conflicts:
# - Ctrl+Shift+arrows (GNOME workspace switching)
# - Ctrl+Shift+t (browser reopen tab)
# - Super+Enter (window manager launcher)
# Remap the kitty shortcut in kitty.conf:
# map Ctrl+Shift+Enter new_window
# To something else:
map ctrl+alt+enter new_window
Common WM Conflicts:
┌──────────────────────────┬────────────────────────────┐
│ Shortcut │ WM / DE │
├──────────────────────────┼────────────────────────────┤
│ Ctrl+Shift+Left/Right │ GNOME workspace switch │
│ Ctrl+Shift+t │ Firefox reopen tab │
│ Alt+Space │ WM window menu │
│ Super+Enter │ i3/Sway launch terminal │
│ Ctrl+Alt+arrows │ KDE workspace switch │
└──────────────────────────┴────────────────────────────┘
# Change kitty prefix to avoid WM conflicts
kitty_mod ctrl+alt
Issue: Kitty Not Starting
Symptom: kitty command fails with no output, segmentation fault, or GPU-related errors.
Root cause: GPU driver issues, missing OpenGL libraries, or incompatible display server.
Fix:
# Check version
kitty --version
# Test with software rendering (disables GPU)
KITTY_DISABLE_WAYLAND=1 kitty --config NONE
# Debug GPU initialization
kitty --debug-rendering 2>&1 | head -30
# Check for missing libraries
ldd $(which kitty) | grep "not found"
# On headless servers, kitty needs a GPU — use tmux instead
Common fixes by environment:
| Environment | Issue | Fix |
|---|---|---|
| Wayland | May crash without Wayland support | KITTY_DISABLE_WAYLAND=1 kitty |
| WSL | GPU acceleration not available | Install kitty-terminfo and use KITTY_DISABLE_WAYLAND=1 |
| Headless/VPS | No GPU hardware | Use tmux with kitty's SSH kitten |
| Old GPU | OpenGL 3.3+ required | KITTY_DISABLE_OPENGL=1 kitty (falls back to CPU) |
| NVIDIA | Proprietary driver needed | sudo apt install nvidia-driver-xxx |
Issue: Colors Not Applying Correctly
Symptom: Colors look washed out, different from what you configured, or themes don't apply.
Root cause: Color scheme collision between kitty.conf, the theme kitten, or terminal multiplexers inside kitty.
Fix:
# Verify current colors
kitty @ get-colors
# Check if a theme is overriding your config
kitty @ kitten themes
# Ensure no tmux inside is overriding colors
# Inside tmux inside kitty, check TERM:
echo $TERM
# Should be "xterm-kitty" not "screen-256color"
# Force true color in tmux config:
set -ga terminal-overrides ",*256col*:Tc"
set -g default-terminal "tmux-256color"
Issue: SSH Terminfo Issues
Symptom: Remote editors (vim, emacs) show wrong colors, cursor shape doesn't change, or italic text doesn't work over SSH.
Root cause: Remote host lacks the xterm-kitty terminfo entry.
Fix:
# Best: use the SSH kitten
kitty +kitten ssh user@host
# Manual: copy terminfo to remote
kitty +kitten transfer /usr/share/terminfo/x/xterm-kitty user@host:/tmp/
ssh user@host "sudo mv /tmp/xterm-kitty /usr/share/terminfo/x/"
# Verify on remote
ssh user@host "infocmp -x xterm-kitty | head -5"
Issue: Images Not Displaying
Symptom: kitty +kitten icat image.png produces garbled output or nothing.
Root cause: The terminal protocol for image display is not supported through multiplexers or over certain SSH configurations.
Fix:
# Test direct in kitty (not inside tmux)
kitty +kitten icat image.png
# Over SSH, ensure TERM=xterm-kitty
ssh -t user@host "kitty +kitten icat image.png"
# Inside tmux, kitty image protocol may not work
# Workaround: use kitty's built-in scrolling instead
| Scenario | Works? | Workaround |
|---|---|---|
| Direct in kitty | ✅ | — |
| Over SSH (TERM=xterm-kitty) | ✅ | Use SSH kitten |
| Inside tmux inside kitty | ❌ | Disable tmux for image viewing |
| Over mosh | ❌ | Use SSH instead |
Diagnostic Commands Summary
# Version
kitty --version
# Config location
kitty --config
# TERM environment
env | grep TERM
# Debug font loading
kitty --debug-fonts
# Debug rendering
kitty --debug-rendering
# Current key mappings
kitty @ ls
# All running kitty instances
kitty @ ls
# Get current colors
kitty @ get-colors
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
| TERM not set to xterm-kitty | Washed out colors over SSH | Use kitty +kitten ssh or copy terminfo |
| Font not installed | Fallback font used, bad glyphs | Install the configured font or change font_family |
| WM capturing shortcut | Shortcut does nothing | Change kitty_mod or remap WM key |
| Config syntax error | Kitty uses defaults silently | Run kitty --debug-config to find errors |
| Running inside tmux without terminfo | Italic/colors broken | Set default-terminal "tmux-256color" and Tc override |
| Outdated GPU driver | Kitty crashes on launch | Update GPU drivers or use KITTY_DISABLE_OPENGL=1 |
| Clipboard not working | Can't paste into GUI apps | Check clipboard_control in kitty.conf |
| SSH agent not forwarded | Can't connect to remote hosts | Use ssh -A or kitty +kitten ssh |
Hands-On Practice
Run these diagnostics on your kitty setup:
# 1. Verify TERM
echo "TERM=$TERM"
[[ "$TERM" == "xterm-kitty" ]] && echo "✅ Correct" || echo "❌ Wrong"
# 2. Check kitty version and config
kitty --version
kitty --config
# 3. Debug font loading
kitty --debug-fonts 2>&1 | head -20
# 4. Test image display
kitty +kitten icat /usr/share/icons/hicolor/48x48/apps/kitty.png 2>/dev/null || echo "❌ icat failed"
# 5. Get current colors
kitty @ get-colors | head -10
# 6. Check for remote terminfo (if you use SSH)
which infocmp && infocmp -x xterm-kitty 2>/dev/null >/dev/null && echo "✅ terminfo OK" || echo "❌ xterm-kitty terminfo missing"