Skip to main content

Troubleshooting

Solutions to common problems with FtVim.

Quick Diagnostics​

Before diving into specific issues, run these commands:

:checkhealth ftvim    " What FtVim needs and what is missing (<leader>FH)
:checkhealth          " Overall health check
:Lazy                 " Plugin status
:Mason                " LSP/tool status
:LspInfo              " Active LSP servers

Icons Not Displaying​

Symptoms: Squares, question marks, or missing icons in the UI.

Solution: Install a Nerd Font and configure your terminal to use it.

Step 1: Install a Nerd Font​

The installer installs JetBrainsMono Nerd Font for you (no root needed). To install it by hand:

On Linux:

mkdir -p ~/.local/share/fonts/JetBrainsMonoNerdFont
curl -fL https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.tar.xz \
  | tar -xJ -C ~/.local/share/fonts/JetBrainsMonoNerdFont
fc-cache -f

On macOS:

brew install --cask font-jetbrains-mono-nerd-font

Other fonts: nerdfonts.com (FiraCode, Hack, ...).

Step 2: Configure Your Terminal​

Set your terminal's font to the Nerd Font you installed:

  • Alacritty: Edit ~/.config/alacritty/alacritty.yml
  • Kitty: Edit ~/.config/kitty/kitty.conf
  • iTerm2: Preferences → Profiles → Text → Font
  • Windows Terminal: Settings → Profiles → Appearance → Font face

LSP Not Working​

Check LSP Status​

:LspInfo

This shows which servers are attached to the current buffer.

Server Not Attached​

Causes:

  1. Server not installed
  2. File not recognized
  3. Server failed to start

Solutions:

  1. Install the server:

    :Mason

    Search for and install the appropriate server.

  2. Check filetype:

    :set ft?

    Ensure the filetype is correct.

  3. Check logs:

    :LspLog

    Look for error messages.

Server Installed But Not Starting​

  1. Verify binary exists:

    which clangd  # or your server

  2. Check PATH in Neovim:

    :echo $PATH

  3. Restart the server:

    :LspRestart

No Completions Appearing​

  1. Ensure LSP is attached: :LspInfo
  2. Check blink.cmp is loaded: :Lazy (look for blink.cmp)
  3. Try triggering manually: Ctrl+Space in insert mode
  4. Check sources: :lua print(vim.inspect(require('blink.cmp').get_sources()))

Treesitter Issues​

Highlighting Wrong or Missing​

  1. Check parser is installed:

    :TSInstallInfo

  2. Reinstall parser:

    :TSInstall <language>

  3. Update parsers:

    :TSUpdate

Parser Installation Fails​

Symptoms: Error during :TSInstall

Causes:

  1. Missing C compiler
  2. Network issues

Solutions:

  1. Install a C compiler:

    • Linux: sudo apt install build-essential or sudo dnf install gcc
    • macOS: xcode-select --install
    • Windows: Install Visual Studio Build Tools or MinGW

  2. Check network: Ensure you can reach GitHub

Plugins Not Loading​

Check Plugin Status​

:Lazy

Look for:

  • Red = error
  • Yellow = warning
  • Green = loaded

Clear Cache and Reinstall​

:Lazy clean
:Lazy install
:Lazy sync

Or manually:

rm -rf ~/.local/share/nvim/lazy
rm -rf ~/.cache/nvim
nvim  # Plugins will reinstall

Plugin Errors on Startup​

  1. Check the error message for the plugin name
  2. Update the plugin: 
    :Lazy update <plugin-name>
  3. Check plugin's GitHub issues for known problems

Performance Issues​

Slow Startup​

  1. Profile startup:

    nvim --startuptime startup.log
    cat startup.log

  2. Check for slow plugins:

    :Lazy profile

  3. Common fixes:

    • Update all plugins: :Lazy update
    • Reduce ensure_installed parsers/servers

Slow Editing Large Files​

  1. Disable Treesitter for large files (see Treesitter docs)
  2. Disable LSP for specific files: 
    :LspStop

Slow Completion​

  1. Reduce completion sources in blink.cmp config
  2. Increase debounce time for completion
  3. Use a faster LSP (e.g., rust-analyzer can be slow on large projects)

Colors/Theme Issues​

Colors Look Wrong​

  1. Ensure true color support:

    :set termguicolors?

    Should show termguicolors.

  2. Check terminal support:

    echo $TERM

    Should be xterm-256color or similar.

  3. For tmux users, add to ~/.tmux.conf:

    set -g default-terminal "tmux-256color"
    set -ag terminal-overrides ",xterm-256color:RGB"

Theme Not Applied​

  1. Check colorscheme is installed:

    :Lazy

  2. Manually set colorscheme:

    :colorscheme tokyonight

Search Issues (ripgrep)​

Grep/Search Not Working​

  1. Check ripgrep is installed:

    which rg

  2. Install ripgrep:

    • Linux: sudo apt install ripgrep or sudo dnf install ripgrep
    • macOS: brew install ripgrep
    • Windows: choco install ripgrep

  3. Verify in Neovim:

    :echo executable('rg')

    Should return 1.

Keymaps Not Working​

Check if Keymap Exists​

:verbose map <leader>ff

Shows where the keymap is defined.

Keymap Conflicts​

:map

Lists all mappings. Look for duplicates.

Leader Key Issues​

  1. Check leader is set:

    :echo mapleader

    Should show a space.

  2. Ensure leader is set before plugins load (FtVim handles this)

Terminal Issues​

Terminal Not Opening​

  1. Check terminal keymap:

    :map <C-\>

  2. Try the other terminals: <leader>tf (float), <leader>th (horizontal), <leader>tv (vertical)

  3. Some terminal emulators don't send Ctrl+\. Use <leader>tf instead, or map another key in lua/config/keymaps.lua:

    vim.keymap.set({ "n", "t" }, "<C-t>", function() Snacks.terminal.toggle() end, { desc = "Terminal" })

Terminal Colors Wrong​

Add to your shell config (~/.bashrc, ~/.zshrc):

export TERM=xterm-256color

Clipboard Issues​

Cannot Paste from System Clipboard​

  1. Check clipboard support:

    :echo has('clipboard')

    Should return 1.

  2. Install clipboard provider:

    • Linux: sudo apt install xclip or xsel
    • macOS: Should work by default
    • WSL: Install win32yank

  3. Use clipboard register:

    • Paste: "+p
    • Copy: "+y

Mason Issues​

Tools Not Installing​

  1. Check Mason log:

    :MasonLog

  2. Verify network access to GitHub and registries

  3. Update Mason registry:

    :MasonUpdate

Tool Not Found After Install​

  1. Restart Neovim after installation
  2. Check Mason bin is in PATH: 
    :echo stdpath('data') .. '/mason/bin'

42 Tools​

See the 42 extra troubleshooting. The usual suspects:

  • No norminette errors: norminette is not installed or not in your PATH (pipx install norminette)
  • clangd can't find your headers: compiledb is not installed (pipx install compiledb) or the project has no Makefile. Run <leader>Fg
  • Everything is disabled (no LSP, no completion): you are in exam mode. The statusline shows EXAM: run :FtVimExam off

Specific Error Messages​

"E5108: Error executing lua"​

Usually a syntax error in your config. Check:

  1. The line number in the error
  2. Recent config changes
  3. Run :checkhealth for more info

"No matching language servers"​

The LSP server for your file's language isn't configured or installed:

  1. :LspInfo to see status
  2. :Mason to install server
  3. Add server to your config

"Pattern not found"​

Your search pattern isn't in the file. Check:

  1. Case sensitivity (use \c for case-insensitive)
  2. Regex escaping (escape special chars with \)

Getting More Help​

Built-in Help​

:help <topic>

Check Health​

:checkhealth

View Messages​

:messages

Shows recent Neovim messages including errors.

Verbose Mode​

Start Neovim with verbose logging:

nvim -V9logfile.log

Report a Bug​

If you've found a bug in FtVim:

  1. Check existing issues
  2. Create a minimal reproduction
  3. Include:
    • Neovim version (:version)
    • FtVim version
    • Steps to reproduce
    • Expected vs actual behavior
    • Error messages

Reset FtVim​

If all else fails, reset to a clean state:

# Backup your config first!
cp -r ~/.config/nvim ~/.config/nvim.bak

# Remove FtVim data
rm -rf ~/.local/share/nvim
rm -rf ~/.cache/nvim
rm -rf ~/.local/state/nvim

# Reinstall
nvim

This reinstalls all plugins and resets caches while preserving your config.