Troubleshooting

Common issues and solutions for Fresh text editor

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:

Force 256-color mode

# 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:

1. 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.

2. View Keyboard Shortcuts

   Use Help → Keyboard Shortcuts to view the complete list of keybindings.

3. 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

1. Open Debug View

   Navigate to Help → Debug Keyboard Events in the menu.

2. Test Keys

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

3. 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:

1. Open View → Calibrate Input from the menu
2. Follow the on-screen prompts to teach Fresh your terminal’s key mappings
3. 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

1. Check LSP Status

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

2. Check Logs

   View the log file:

   tail -f ~/.local/state/fresh/logs/fresh.log
   
3. Verify LSP Installation

   Ensure the language server is installed and in your PATH:

   which rust-analyzer  # for Rust
   which typescript-language-server  # for TypeScript
   
4. 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 Style

Options:

• 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

1. Enable Mouse Capture

   Check if mouse support is enabled:

   View → Mouse Support (toggle)

   Or in config:

   {
     "editor": {
       "mouse_capture": true
     }
   }
   
2. Terminal Support

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

3. 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:

1. Check if workspace restoration is enabled:

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

2. Or use the CLI flag to skip restoration:

   fresh --no-restore
   

3. 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

1. Check Plugin Directory

   Plugins should be in:

   ~/.config/fresh/plugins/
   
2. Verify Plugin Structure

   A plugin needs:

   • plugin.json (manifest)
   • Main JavaScript file
3. Check Logs

   Plugin errors appear in:

   tail -f ~/.local/state/fresh/logs/fresh.log
   
4. 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:

1. Fresh version: fresh --version
2. Operating system and terminal emulator
3. Steps to reproduce
4. Relevant log output
5. Configuration (if related)

See Also

• CLI Commands - Command-line reference
• Keybindings - Keyboard shortcuts
• Privacy - Telemetry and data collection