Troubleshooting

Common issues, platform notes, and how to get help.

First step: Always run blade doctor first. It checks your GPU, fonts, config, and PTY and provides specific fix suggestions.

Common Issues

GPU not detected

Blade requires a GPU with Vulkan, Metal, DX12, or OpenGL support.

Fix: Run blade doctor to see which GPU backend is available. Update your graphics drivers to the latest version. On Linux, ensure Vulkan drivers are installed (vulkan-tools package).

Font not found

Blade can't find the font specified in your config.

Fix: Check the family name in [font] matches an installed font exactly. Run blade doctor to see which fonts are detected. The fallback chain (Consolas, Noto Sans Mono, DejaVu Sans Mono) will be used if the primary font is missing.

Config not loading

Blade starts but ignores your configuration changes.

Fix: Check the config file path. Run blade --config ./blade.toml to test a specific file. Validate your TOML syntax — a missing quote or bracket will cause the entire file to be skipped. Blade falls back to defaults on parse errors.

Colors look wrong

Text colors don't match your theme or appear washed out.

Fix: Ensure theme is set correctly in [colors] (e.g., "catppuccin-mocha" not "catppuccin mocha"). If using manual colors, verify hex values include the # prefix. Run echo -e "\033[38;2;255;0;0mRed\033[0m" to test true color support.

Shift+Enter not working

Pressing Shift+Enter submits instead of creating a new line in Claude Code.

Fix: This should work out of the box. Blade sends the ESC + CR sequence that Claude Code expects. Ensure you're running Blade directly (not inside another terminal emulator like tmux or screen, which may intercept the key).

Windows

ConPTY requirements

Blade uses Windows ConPTY for its pseudo-terminal. This requires Windows 10 version 1809 (October 2018 Update) or later. Earlier versions of Windows are not supported.

Antivirus false positives

Windows Defender SmartScreen

On first launch, Windows may show a SmartScreen warning for unsigned binaries. Click "More info" then "Run anyway". Alternatively, install via scoop install blade to avoid this.

macOS

Gatekeeper

macOS may block Blade from launching because it's not signed with an Apple Developer ID. To allow it:

  1. Open System Settings > Privacy & Security
  2. Scroll down and click "Open Anyway" next to the Blade warning

Alternatively, install via brew install blade-term which handles code signing.

Metal GPU requirement

Blade uses Metal for GPU rendering on macOS. All Macs from 2012 onward support Metal. If you're on an older Mac, Blade will fall back to OpenGL.

Linux

Vulkan drivers

Blade prefers Vulkan for rendering on Linux. Install the appropriate driver package:

Verify with vulkaninfo. If Vulkan is unavailable, Blade falls back to OpenGL.

Wayland vs X11

Blade supports both Wayland and X11 via winit. On Wayland, ensure XDG_SESSION_TYPE=wayland is set. If you experience issues, try running with WINIT_UNIX_BACKEND=x11 blade to force X11 mode.

Getting Help

If you've run blade doctor and checked this guide but still have issues:

  1. Open a new issue with your blade doctor output, platform details, and steps to reproduce
# Include this output when filing an issue $ blade doctor $ blade --version