> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Accordion title="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`
</Accordion>

<Accordion title="256 colors">
  Extended color palette with 256 colors. Used by:

  * xterm-256color
  * Most terminal emulators as fallback
  * tmux (by default)
</Accordion>

<Accordion title="16 colors">
  Basic ANSI color palette. Used by:

  * Linux console
  * Very old terminals
  * GNU Screen
</Accordion>

### Terminal Multiplexers

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

<Warning>
  **GNU Screen** does not support truecolor. Fresh automatically uses 256 colors when `TERM` starts with `screen`.
</Warning>

<Note>
  **tmux** supports 256 colors by default. Some configurations support truecolor with `TERM=tmux-direct`.
</Note>

### Manual Override

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

<CodeGroup>
  ```bash Force 256-color mode theme={null}
  # Recommended for GNU Screen
  FRESH_COLOR_MODE=256 fresh
  ```

  ```bash Force 16-color mode theme={null}
  FRESH_COLOR_MODE=16 fresh
  ```

  ```bash Force truecolor theme={null}
  # If auto-detection is wrong
  FRESH_COLOR_MODE=truecolor fresh
  ```
</CodeGroup>

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

```bash theme={null}
# 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

<Steps>
  <Step title="Open Debug View">
    Navigate to **Help → Debug Keyboard Events** in the menu.
  </Step>

  <Step title="Test Keys">
    Press any key to see its code, modifiers, and event type.
  </Step>

  <Step title="Actions">
    * Press `c` to clear history
    * Press `q` or `Esc` to close
  </Step>
</Steps>

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

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

### LSP Server Not Starting

<Steps>
  <Step title="Check LSP Status">
    Open **Help → LSP Status** to see which language servers are running.
  </Step>

  <Step title="Check Logs">
    View the log file:

    ```bash theme={null}
    tail -f ~/.local/state/fresh/logs/fresh.log
    ```
  </Step>

  <Step title="Verify LSP Installation">
    Ensure the language server is installed and in your PATH:

    ```bash theme={null}
    which rust-analyzer  # for Rust
    which typescript-language-server  # for TypeScript
    ```
  </Step>

  <Step title="Restart LSP">
    Use **LSP → Restart** from the command palette.
  </Step>
</Steps>

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

<Accordion title="Cursor not visible">
  Try changing the cursor style:

  **View → Settings → Editor → Cursor Style**

  Options:

  * `block` (default)
  * `underline`
  * `bar`

  Or in `config.json`:

  ```json theme={null}
  {
    "editor": {
      "cursor_style": "underline"
    }
  }
  ```
</Accordion>

<Accordion title="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
</Accordion>

### Weird Characters or Boxes

<Warning>
  Missing font glyphs or wrong encoding can cause display issues.
</Warning>

**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

<Steps>
  <Step title="Enable Mouse Capture">
    Check if mouse support is enabled:

    **View → Mouse Support** (toggle)

    Or in config:

    ```json theme={null}
    {
      "editor": {
        "mouse_capture": true
      }
    }
    ```
  </Step>

  <Step title="Terminal Support">
    Verify your terminal supports mouse events. Most modern terminals do, but some may require configuration.
  </Step>

  <Step title="GPM (Linux Console)">
    On the Linux console (not in a terminal emulator), Fresh uses GPM for mouse support. Ensure `gpm` service is running:

    ```bash theme={null}
    sudo systemctl status gpm
    ```
  </Step>
</Steps>

## Session & Workspace Issues

### Session Not Restoring

If your workspace doesn't restore on startup:

1. Check if workspace restoration is enabled:
   ```json theme={null}
   {
     "editor": {
       "restore_session": true
     }
   }
   ```

2. Or use the CLI flag to skip restoration:
   ```bash theme={null}
   fresh --no-restore
   ```

3. Check session files:
   ```bash theme={null}
   ls ~/.local/state/fresh/sessions/
   ```

### Cannot Attach to Session

<Accordion title="Session not found">
  List active sessions:

  ```bash theme={null}
  fresh --cmd session list
  ```

  The session may have been terminated or doesn't exist yet.
</Accordion>

<Accordion title="Permission denied">
  Check socket permissions:

  ```bash theme={null}
  ls -l ~/.local/state/fresh/sockets/
  ```

  You may need to clean up stale socket files.
</Accordion>

## Plugin Issues

### Plugin Not Loading

<Steps>
  <Step title="Check Plugin Directory">
    Plugins should be in:

    ```bash theme={null}
    ~/.config/fresh/plugins/
    ```
  </Step>

  <Step title="Verify Plugin Structure">
    A plugin needs:

    * `plugin.json` (manifest)
    * Main JavaScript file
  </Step>

  <Step title="Check Logs">
    Plugin errors appear in:

    ```bash theme={null}
    tail -f ~/.local/state/fresh/logs/fresh.log
    ```
  </Step>

  <Step title="Test Without Plugins">
    Disable plugins temporarily:

    ```bash theme={null}
    fresh --no-plugins
    ```
  </Step>
</Steps>

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

<CardGroup cols={2}>
  <Card title="View Logs" icon="file-lines">
    Main log file:

    ```bash theme={null}
    tail -f ~/.local/state/fresh/logs/fresh.log
    ```
  </Card>

  <Card title="Show Paths" icon="folder">
    See all Fresh directories:

    ```bash theme={null}
    fresh --cmd config paths
    ```
  </Card>

  <Card title="Dump Config" icon="gear">
    View effective configuration:

    ```bash theme={null}
    fresh --cmd config show
    ```
  </Card>

  <Card title="Check LSP" icon="server">
    LSP status and diagnostics:

    **Help → LSP Status**
  </Card>
</CardGroup>

### 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](/reference/cli-commands) - Command-line reference
* [Keybindings](/reference/keybindings) - Keyboard shortcuts
* [Privacy](/reference/privacy) - Telemetry and data collection