Debugging Kitty
Kitty provides several debug modes, logging facilities, and diagnostic kittens to help troubleshoot issues. This lesson covers every debugging tool available.
Learning Focus
Learn to use kitty's built-in debugging tools systematically — from config validation to GPU rendering diagnostics to protocol inspection.
Debug Modes
Rendering Debug
# Show GPU rendering pipeline details
kitty --debug-rendering
Output includes:
[debug] OpenGL vendor: NVIDIA Corporation
[debug] OpenGL renderer: NVIDIA GeForce RTX 3060/PCIe/SSE2
[debug] OpenGL version: 4.6.0 NVIDIA 535.154.05
[debug] Texture atlas size: 2048x2048
[debug] Cell dimensions: 8x17
[debug] VSync: on
[debug] Synchronous: off
Input Debug
# Show all keyboard and mouse input events
kitty --debug-input
This prints every key press and mouse event to stdout. Use it to diagnose:
- Whether kitty is receiving the key at all
- What modifier combos are being detected
- Mouse button and coordinate data
Font Debug
# Show font discovery and fallback chain
kitty --debug-fonts
Useful when glyphs are missing or the wrong font is being used.
Keyboard Debug
# Log all key events to a file for analysis
kitty --debug-keyboard 2>keys.log
# In another terminal, tail the log
tail -f keys.log
Configuration Debugging
# Validate config without starting kitty
kitty --debug-config
# Check what config file kitty is using
kitty --config
# Run with no config (ships default behavior)
kitty --config /dev/null
# Check for deprecated or ignored settings
kitty --debug-config 2>&1 | grep -i "deprecated\|ignored\|unknown"
tip
Always test with --config /dev/null before reporting a bug — it confirms the issue is not in your config.
Environment Debugging
# Dump all command-line arguments kitty was called with
kitty --dump-args
# Dump the environment kitty sees
kitty --env
# Check what TERM is set to
echo $TERM
# Check if KITTY_WINDOW_ID is set (SSH identification)
echo $KITTY_WINDOW_ID
Protocol Support
Use the query_terminal kitten to check what terminal features are supported:
# Get the full terminal capabilities report
kitty +kitten query_terminal
# Check specific capabilities
kitty +kitten query_terminal | grep -E "true_color|sync|kitty_keyboard"
The output includes:
| Capability | Description |
|---|---|
true_color | 24-bit color support |
kitty_keyboard | Kitty's enhanced keyboard protocol |
sync | Synchronized updates |
clipboard | OSC 52 clipboard access |
image_protocol | Kitty's image display protocol |
unicode_version | Active Unicode version |
Checking Terminal Protocol Support
# Check for kitty protocol support
echo $TERM_PROGRAM
echo $TERM_PROGRAM_VERSION
# Verify the kitty protocol is being used
printf '\e[?u' # Request keyboard protocol status
# Check underline tooltip support (kitty 0.31+)
kitty @ get-colors | grep -i underline
Debugging Specific Subsystems
Cursor Issues
# Check cursor shape and style
grep cursor_shape ~/.config/kitty/kitty.conf
# Test cursor shapes in order
kitty --config <(echo "cursor_shape block")
kitty --config <(echo "cursor_shape beam")
kitty --config <(echo "cursor_shape underline")
Clipboard Debugging
# Check clipboard control settings
grep clipboard_control ~/.config/kitty/kitty.conf
# Test clipboard read/write
kitty +kitten clipboard
# Check if OSC 52 is being passed through
echo -e '\e]52;c;'"$(echo "test" | base64)"'\a'
SSH Debugging
# Test SSH with maximum verbosity
kitty +kitten ssh -v user@host
# Check if terminfo was transferred
ssh user@host "infocmp -x xterm-kitty" 2>/dev/null && echo "terminfo OK" || echo "❌ missing"
# Test terminal features over SSH
ssh -t user@host "echo \$TERM && kitty +kitten query_terminal"
Logging
# Capture all stderr output for analysis
kitty 2>kitty-debug.log
# Capture keyboard events to file
kitty --debug-keyboard 2>kitty-keys.log
# Combine multiple debug flags
kitty --debug-rendering --debug-input 2>kitty-debug.log
# Run in foreground for live debugging
kitty --debug-input --single-shot 2>&1 | tee kitty-live.log
Debugging with Multiple Instances
# List all running kitty instances
kitty @ ls
# Send remote control commands to a specific instance
kitty @ --to unix:/tmp/kitty-socket-name new-window
# Get debug info from a specific instance
kitty @ --to unix:/tmp/kitty-socket-name get-colors
Reporting Issues
When reporting a bug to the kitty project, include:
# Required diagnostic output
{
echo "=== Version ==="
kitty --version
echo "=== Config ==="
kitty --config
echo "=== OS ==="
uname -a
echo "=== Rendering ==="
kitty --debug-rendering 2>&1
echo "=== Config Debug ==="
kitty --debug-config 2>&1
echo "=== Font Debug ==="
kitty --debug-fonts 2>&1
echo "=== Env ==="
env | grep -E "TERM|KITTY|WAYLAND|DISPLAY" | sort
} > kitty-bug-report.txt
# Always test with --config /dev/null first
Common Debugging Commands
| Command | Purpose | When to Use |
|---|---|---|
kitty --version | Check kitty version | First step in any debug |
kitty --config | Show config file path | Config not loading |
kitty --debug-config | Validate config syntax | Config parsing errors |
kitty --debug-rendering | GPU pipeline status | Visual glitches, slow rendering |
kitty --debug-input | Keyboard/mouse events | Shortcuts not responding |
kitty --debug-fonts | Font discovery chain | Missing glyphs, wrong font |
kitty --debug-keyboard 2>keys.log | Key event log | Complex keyboard issues |
kitty +kitten query_terminal | Protocol capabilities | Feature not working |
kitty @ ls | List running instances | Remote control issues |
kitty @ get-colors | Current effective colors | Theme not applying |
kitty --config /dev/null | Run with defaults | Isolate config bug |
kitty +kitten ssh -v | Debug SSH connection | Terminfo/TERM issues |
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
Not testing with --config /dev/null | Blaming kitty for config bug | Always isolate with bare kitty first |
Forgetting 2> redirect for debug | No output from debug flags | Kitty debug output is on stderr |
| Too many debug flags at once | Overwhelming output | Start with --debug-config, then add one flag at a time |
| Ignoring TERM_PROGRAM | Wrong protocol negotiation | Ensure TERM_PROGRAM=kitty over SSH |
| Debugging inside tmux | TMUX intercepts kitty protocol | Test all protocol features outside tmux first |
| Not running latest version | Bug already fixed | Check kitty --version against latest release |
Missing xterm-kitty on remote | Features broken over SSH | Use kitty +kitten ssh or copy terminfo manually |
Hands-On Practice
# 1. Generate a complete bug report
kitty --version > /tmp/kitty-diag.txt
kitty --config >> /tmp/kitty-diag.txt
kitty --debug-config 2>> /tmp/kitty-diag.txt
kitty --debug-rendering 2>> /tmp/kitty-diag.txt
kitty --debug-fonts 2>> /tmp/kitty-diag.txt
echo "---" >> /tmp/kitty-diag.txt
env | grep -E "TERM|KITTY" >> /tmp/kitty-diag.txt
echo "Diagnostic saved to /tmp/kitty-diag.txt"
# 2. Run kitty with no config
kitty --config /dev/null &
# 3. Test keyboard input debugging (run in a terminal, then type)
# kitty --debug-input
# Look at the raw key event output
# 4. Query terminal capabilities
kitty +kitten query_terminal | head -30
# 5. List all running kitty instances
kitty @ ls
# 6. Check config for errors
kitty --debug-config 2>&1 | grep -i "error\|warning\|unknown\|deprecated"