Troubleshooting

This guide covers common issues you may encounter when using Fresh and how to resolve them.

Terminal Color Support

Fresh automatically detects your terminal’s color capability and converts theme colors accordingly. Most modern terminals support 24-bit “truecolor”, but some terminals and multiplexers have limited support.

Color Modes

Truecolor (24-bit)

Full RGB color support with 16 million colors. Used by modern terminals like:

Kitty
Alacritty
iTerm2
Windows Terminal
Most terminals with COLORTERM=truecolor

256 colors

Extended color palette with 256 colors. Used by:

xterm-256color
Most terminal emulators as fallback
tmux (by default)

16 colors

Basic ANSI color palette. Used by:

Linux console
Very old terminals
GNU Screen

Terminal Multiplexers

GNU Screen and tmux add a layer between your terminal and Fresh, which can affect color rendering:

GNU Screen does not support truecolor. Fresh automatically uses 256 colors when TERM starts with screen.

tmux supports 256 colors by default. Some configurations support truecolor with TERM=tmux-direct.

Manual Override

If colors look wrong, you can force a specific color mode with the FRESH_COLOR_MODE environment variable:

# Recommended for GNU Screen
FRESH_COLOR_MODE=256 fresh

Common Color Issues

Symptom	Likely Cause	Solution
Colors look completely wrong	Truecolor detected but not supported	Use `FRESH_COLOR_MODE=256`
Weird artifacts/rendering issues	Terminal multiplexer interference	Try `FRESH_COLOR_MODE=256` or check TERM
Very limited/ugly colors	16-color mode detected	Check your terminal supports 256 colors

Checking Your Terminal

# Check TERM variable
echo $TERM

# Check COLORTERM (if set, indicates truecolor support)
echo $COLORTERM

Keybinding Issues

Keybinding Not Working

If a keybinding isn’t working as expected:

Check the Command Palette Open Command Palette (Ctrl+P or ^P) and type the command name. If a keybinding is assigned, it will be shown alongside the command.
View Keyboard Shortcuts Use Help → Keyboard Shortcuts to view the complete list of keybindings.
Debug Keyboard Events Use Help → Debug Keyboard Events to see exactly what key codes your terminal sends to Fresh.

Debug Keyboard Events

This tool shows raw terminal events before any translation, helping diagnose issues like:

Missing modifier keys (e.g., Ctrl+Shift+Home arriving as just Ctrl+Home)
Terminal or OS intercepting keys before they reach Fresh
Incorrect escape sequences from your terminal

Open Debug View

Navigate to Help → Debug Keyboard Events in the menu.

Test Keys

Press any key to see its code, modifiers, and event type.

Actions

Press c to clear history
Press q or Esc to close

Input Calibration

Some terminals send non-standard escape sequences. If certain key combinations don’t work:

Open View → Calibrate Input from the menu
Follow the on-screen prompts to teach Fresh your terminal’s key mappings
Calibration is saved to ~/.config/fresh/key-calibration.json

This is especially useful for:

Exotic terminal emulators
Remote SSH sessions
Terminals with custom key mappings

Performance Issues

Slow Syntax Highlighting

Large files

For very large files (>1MB), consider:

Disabling syntax highlighting temporarily
Using tree-sitter instead of TextMate grammars (generally faster)
Splitting the file into smaller chunks if possible

Complex grammars

Some TextMate grammars are computationally expensive. Try:

Switching to tree-sitter: View → Settings → Editor → Highlighter → tree-sitter
Using a simpler theme
Disabling certain highlighting features

LSP Server Not Starting

Check LSP Status

Open Help → LSP Status to see which language servers are running.

Check Logs

View the log file:

tail -f ~/.local/state/fresh/logs/fresh.log

Verify LSP Installation

Ensure the language server is installed and in your PATH:

which rust-analyzer  # for Rust
which typescript-language-server  # for TypeScript

Restart LSP

Use LSP → Restart from the command palette.

File Not Found or Permission Errors

If Fresh can’t open or save files:

Check file permissions: ls -l file.txt
Verify the file exists and path is correct
Check if another process has the file locked
Ensure you have write permissions to the directory

Display Issues

Cursor Rendering Problems

Cursor not visible

Try changing the cursor style:View → Settings → Editor → Cursor StyleOptions:

block (default)
underline
bar

Or in config.json:

{
  "editor": {
    "cursor_style": "underline"
  }
}

Cursor flickers or disappears

Some terminals have issues with cursor rendering. Try:

Different cursor styles
Updating your terminal emulator
Checking if terminal has cursor-related settings

Weird Characters or Boxes

Missing font glyphs or wrong encoding can cause display issues.

Font Issues:

Ensure your terminal uses a font with good Unicode coverage
Try fonts like: FiraCode, JetBrains Mono, Cascadia Code, or Iosevka

Encoding Issues:

Check file encoding: View → Settings → Encoding
Fresh supports: UTF-8, UTF-16, GBK, Shift-JIS, EUC-KR, and more
Use File → Reload with Encoding to try different encodings

Mouse Not Working

Enable Mouse Capture

Check if mouse support is enabled:View → Mouse Support (toggle)Or in config:

{
  "editor": {
    "mouse_capture": true
  }
}

Terminal Support

Verify your terminal supports mouse events. Most modern terminals do, but some may require configuration.

GPM (Linux Console)

On the Linux console (not in a terminal emulator), Fresh uses GPM for mouse support. Ensure gpm service is running:

sudo systemctl status gpm

Session & Workspace Issues

Session Not Restoring

If your workspace doesn’t restore on startup:

Check if workspace restoration is enabled:

{
  "editor": {
    "restore_session": true
  }
}

Or use the CLI flag to skip restoration:
```
fresh --no-restore
```
Check session files:
```
ls ~/.local/state/fresh/sessions/
```

Cannot Attach to Session

Session not found

List active sessions:

fresh --cmd session list

The session may have been terminated or doesn’t exist yet.

Permission denied

Check socket permissions:

ls -l ~/.local/state/fresh/sockets/

You may need to clean up stale socket files.

Plugin Issues

Plugin Not Loading

Check Plugin Directory

Plugins should be in:

~/.config/fresh/plugins/

Verify Plugin Structure

A plugin needs:

plugin.json (manifest)
Main JavaScript file

Check Logs

Plugin errors appear in:

tail -f ~/.local/state/fresh/logs/fresh.log

Test Without Plugins

Disable plugins temporarily:

fresh --no-plugins

Plugin Errors

If a plugin throws errors:

Check plugin compatibility with your Fresh version
Review plugin documentation
Check if plugin dependencies are installed
Report issues to the plugin author

Advanced Topics

Visual Regression Testing

Fresh uses visual regression testing to catch unintentional UI changes. See the repository’s docs/VISUAL_REGRESSION_TESTING.md for details.

Getting More Help

View Logs

Main log file:

tail -f ~/.local/state/fresh/logs/fresh.log

Show Paths

See all Fresh directories:

fresh --cmd config paths

Dump Config

View effective configuration:

fresh --cmd config show

Check LSP

LSP status and diagnostics:Help → LSP Status

Reporting Bugs

When reporting issues, please include:

Fresh version: fresh --version
Operating system and terminal emulator
Steps to reproduce
Relevant log output
Configuration (if related)

Getting Started

Core Features

Configuration

Advanced Features

Plugins

Reference

Documentation Index

​Terminal Color Support

​Color Modes

​Terminal Multiplexers

​Manual Override

​Common Color Issues

​Checking Your Terminal

​Keybinding Issues

​Keybinding Not Working

​Debug Keyboard Events

​Input Calibration

​Performance Issues

​Slow Syntax Highlighting

​LSP Server Not Starting

​File Not Found or Permission Errors

​Display Issues

​Cursor Rendering Problems

​Weird Characters or Boxes

​Mouse Not Working

​Session & Workspace Issues

​Session Not Restoring

​Cannot Attach to Session

​Plugin Issues

​Plugin Not Loading

​Plugin Errors

​Advanced Topics

​Visual Regression Testing

​Getting More Help

View Logs

Show Paths

Dump Config

Check LSP

​Reporting Bugs

​See Also

Build docs developers (and LLMs) love

Terminal Color Support

Color Modes

Terminal Multiplexers

Manual Override

Common Color Issues

Checking Your Terminal

Keybinding Issues

Keybinding Not Working

Debug Keyboard Events

Input Calibration

Performance Issues

Slow Syntax Highlighting

LSP Server Not Starting

File Not Found or Permission Errors

Display Issues

Cursor Rendering Problems

Weird Characters or Boxes

Mouse Not Working

Session & Workspace Issues

Session Not Restoring

Cannot Attach to Session

Plugin Issues

Plugin Not Loading

Plugin Errors

Advanced Topics

Visual Regression Testing

Getting More Help

Reporting Bugs

See Also