Troubleshooting

Solutions to common problems.

General Diagnostics

Always start with:

:checkhealth

This shows the status of all major components.

Check messages:

:messages

Shows any warnings or errors.

View logs:

# Neovim logs
tail -f ~/.local/share/nvim/nvim.log

# LSP logs
tail -f ~/.local/share/nvim/lsp.log

Installation Issues

Error: Python not found

Problem: python3: command not found

Solution: Install Python:

# macOS
brew install python@3.11

# Linux (Debian/Ubuntu)
sudo apt-get install python3

Error: Git clone fails

Problem: fatal: unable to access repository

Possible causes:

1. Internet connection issue - check connectivity

2. Wrong URL - verify repository URL

3. Git not installed - install Git

Error: Permission denied

Problem: /Users/cs/.config/nvim: Permission denied

Solution: Fix permissions:

chmod -R 755 ~/.config/nvim
chmod -R 755 ~/.virtualenvs/nvim

Error: No space left on device

Check disk space:

df -h

Free up space and retry installation.

Neovim Not Found

Error: nvim: command not found

Cause: Neovim not installed or not in PATH.

Fix for Homebrew installation:

brew install neovim

Fix for binary installation:

1. Verify binary exists:

   ls -la ~/apps/neovim/nvim.app/bin/nvim  # macOS
   ls -la ~/apps/neovim/nvim.appimage       # Linux
   

2. Add to PATH:

   export PATH=$HOME/apps/neovim/nvim.app/bin:$PATH
   

3. Add to shell profile (~/.bashrc or ~/.zshrc):

   export PATH=$HOME/.local/bin:$PATH
   

Verify installation:

which nvim
nvim --version

Python Virtual Environment Issues

Error: Virtual environment not found

Solution: Create it manually:

python3 -m venv ~/.virtualenvs/nvim
source ~/.virtualenvs/nvim/bin/activate
pip install pynvim zuban ruff "darker[isort]"
deactivate

Error: ModuleNotFoundError: No module named ‘pynvim’

Solution: Install missing package:

~/.virtualenvs/nvim/bin/pip install pynvim

Error: Python version mismatch

Neovim uses the Python from ~/.virtualenvs/nvim/. To check:

~/.virtualenvs/nvim/bin/python --version

Wrong Python being used:

Configure which Python in lua/lsp/lsp.lua:

settings = {
    python = {
        pythonPath = os.getenv('HOME') .. '/.virtualenvs/nvim/bin/python',
    }
}

LSP Not Working

Error: LSP not activating

1. Check Python path:

   :checkhealth python
   

2. Verify Zuban installed:

   ~/.virtualenvs/nvim/bin/python -m pip list | grep zuban
   

3. If missing, install it:

   ~/.virtualenvs/nvim/bin/pip install zuban
   

4. Restart Neovim

Error: Go to definition not working

Possible causes:

1. LSP still analyzing - wait a moment

2. Symbol is built-in (may not work for builtins)

3. LSP not active - check with :LspInfo

Try:

:LspRestart

Error: Code completion not showing

1. Ensure you’re in insert mode

2. Press <C-x><C-o> explicitly

3. Check :LspInfo for errors

4. Try: :LspRestart

Error: Too many diagnostic errors

Diagnostics may be overly aggressive. Configure in lua/lsp/lsp.lua:

analysis = {
    typeCheckingMode = "basic",  -- Use "off" to disable
}

Error: LSP too slow

1. Close large files (LSP struggles with huge files)

2. Configure to skip large files:

   function on_attach(client, bufnr)
       if vim.fn.getfsize(vim.fn.bufname(bufnr)) > 1000000 then
           client.stop()  -- Don't analyze files > 1MB
       end
   end
   

3. Reduce diagnostic checking

4. Try: :LspRestart

FZF Not Working

Error: FZF not found

Install FZF:

# macOS
brew install fzf

# Linux
sudo apt-get install fzf

Error: Ripgrep not found (used by FZF)

Install Ripgrep:

# macOS
brew install ripgrep

# Linux
sudo apt-get install ripgrep

Commands not responding:

1. Verify FZF installed: fzf --version

2. Verify Ripgrep installed: rg --version

3. Restart Neovim

4. Check if directory is huge (too many files)

Slow searches:

Large directories slow FZF. Use:

• <C-g> (git files) instead of <C-f> (all files)

• Add exclusions in lua/plugin/fzf-lua.lua

Missing search results:

Files may be in .gitignore. To search all files:

<C-f>  " All files, not just git-tracked

Keybinding Issues

Error: Keybinding not working

1. Check it’s mapped correctly:

   :map <leader>x  " Shows what's mapped to <leader>x
   

2. Check for typos in lua/plugin/which-key.lua

3. Verify syntax is correct

4. Restart Neovim

Error: which-key menu not showing

1. Check which-key is installed:

   :checkhealth
   

2. If not installed, reinstall plugins:

   :Lazy sync
   

3. Verify which-key is required in init.lua

4. Restart Neovim

Error: Keybinding conflicts

If a keybinding does something unexpected:

1. View all keybindings:

   :map  " All mappings
   :map <leader>  " Leader key mappings
   

2. Find conflicting binding

3. Comment out or change it in lua/plugin/which-key.lua

4. Restart Neovim

Syntax Highlighting Issues

Error: Treesitter parsers missing

Install parsers:

:TSInstall python lua comment vim vimdoc c sql query

Error: Colors look wrong

1. Check colorscheme:

   :colorscheme  " Shows current scheme
   

2. Verify terminal supports colors:

   echo $TERM
   # Should be: xterm-256color or similar
   

3. Ensure Nerd Font is installed:

   • See Requirements for Nerd Font setup

Error: Icons not displaying

1. Install a Nerd Font (see Requirements)

2. Set as terminal font in settings

3. Restart terminal and Neovim

Performance Issues

Slow startup:

Profile to find bottleneck:

nvim --startuptime startup.log +q
sort -k2 -n startup.log | tail -20

Common culprits:

• Heavy plugins

• Large config files

• Disk I/O issues

• Too many language servers

Slow editing:

1. Close unused buffers: :bd

2. Disable expensive features:

   :set updatetime=500  " Increase LSP check interval
   

3. Close very large files

4. Check disk space

High CPU usage:

1. Check which plugin:

   :profile start profile.log
   :profile func *
   " ... do something slow ...
   :profile pause
   " Check profile.log
   

2. Disable that plugin or configure it

3. Restart Neovim

Configuration Errors

Error: Lua syntax error

Check the error:

:checkhealth
:messages

Likely causes:

• Missing comma in table

• Unclosed parenthesis

• Wrong function name

• Missing quotes

Error: File not found

When loading configuration:

Error: No such file or directory: lua/plugin/missing.lua

Solution: Create the missing file or remove the require statement.

Error: Undefined variable

Error: undefined global 'some_variable'

Solution: Define the variable or check the name.

File Permissions

Error: Permission denied

chmod -R 755 ~/.config/nvim
chmod -R 755 ~/.dotfiles/nvim

Cannot create file:

Check directory permissions:

ls -la ~/.config/

Neovim Crashes

Crash when opening file:

1. Note which file causes crash

2. Try disabling plugins one by one

3. Check logs: tail -f ~/.local/share/nvim/nvim.log

4. Report issue with file and plugin info

Crash on startup:

1. Check :checkhealth for errors

2. Try starting with minimal config:

   nvim -u NONE
   

3. If works, find problematic plugin

4. Check for corrupted config files

Crash with specific command:

1. Note which command

2. Try in safe mode: nvim -u NONE -i NONE

3. Report with exact reproduction steps

Terminal-Related Issues

Error: Colors not working in terminal

Check terminal color support:

echo $TERM
# Should show: xterm-256color, screen-256color, tmux, etc.

If not 256 colors:

export TERM=xterm-256color

Add to ~/.bashrc or ~/.zshrc to make permanent.

Error: Scrolling issues

In Neovim:

set mouse=a  " Enable mouse

Or in configuration:

vim.opt.mouse = "a"

Error: Clipboard not working

Requires system clipboard support:

brew install reattach-to-user-namespace  # macOS
sudo apt-get install xclip               # Linux

Verify in Neovim:

:checkhealth clipboard

Git-Related Issues

Error: Git hooks failing

If a hook blocks commits:

1. Edit .git/hooks/ to see what’s running

2. Or bypass with: git commit --no-verify

3. Fix the issue that triggered the hook

Error: Not a git repository

Neovim features (like gitsigns) need git repo:

git init

Or clone the repo in a git project.

Getting Help

If you can’t solve the issue:

1. Run diagnostics:

   :checkhealth
   :messages
   

2. Check logs:

   tail -50 ~/.local/share/nvim/nvim.log
   

3. Search issues:

   • Check GitHub issues for similar problems

   • Search troubleshooting guide

4. Report issue:

   • Include :checkhealth output

   • Include error messages and logs

   • Include Neovim version: nvim --version

   • Include minimal reproduction steps

5. Ask community:

   • Neovim forums

   • Discord/Slack communities

   • GitHub discussions

Common Messages

Message: “Syntax error in”

• Check Lua file syntax

• Look for missing commas, quotes, parentheses

• Check line numbers in error

Message: “Unknown option”

• Check option name spelling

• Verify option exists in your Neovim version

• Check :help for correct syntax

Message: “Plugin failed to load”

• Plugin may not be installed

• Check for typos in require statement

• Verify dependencies are met

• Restart Neovim

Quick Fixes Summary

Most common quick fixes:

1. Restart Neovim - Solves 30% of issues

2. Run ``:checkhealth`` - Diagnoses most issues

3. Reinstall plugins - :Lazy clean then :Lazy sync

4. Check virtual environment - Python issues often here

5. View error messages - :messages shows what’s wrong

6. Check installation - Run python3 install.py again

If none of these work, see the detailed sections above or Development for how to debug further.