Troubleshooting¶

Common issues and solutions for Neovim and LazyVim.

Diagnostic Commands¶

Health Check¶

Run comprehensive diagnostics:

:checkhealth

Check specific components:

:checkhealth lazy
:checkhealth lsp
:checkhealth mason
:checkhealth nvim-treesitter

Plugin Information¶

:Lazy          " Plugin manager UI
:Lazy log      " View update log
:Lazy profile  " Startup profile

LSP Information¶

:LspInfo       " Active LSP clients
:LspLog        " LSP debug log
:Mason         " LSP server manager

Plugin Issues¶

Plugins Not Loading¶

Check lazy-lock.json: Ensure it exists and is valid JSON
Sync plugins: Run :Lazy sync
Check for errors: Run :Lazy

" Force reinstall all plugins
:Lazy restore

Plugin Conflicts¶

Disable conflicting plugins:

-- lua/plugins/disabled.lua
return {
  { "conflicting-plugin", enabled = false },
}

Startup Errors¶

Check startup profile:

:Lazy profile

Run Neovim without config to isolate:

nvim --clean
nvim -u NONE

LSP Issues¶

LSP Not Starting¶

Check if installed: :Mason
Check LspInfo: :LspInfo
Check logs: :LspLog

Install Missing Server¶

:MasonInstall pyright

Or automatically:

-- lua/plugins/lsp.lua
return {
  "williamboman/mason-lspconfig.nvim",
  opts = {
    ensure_installed = { "pyright", "ruff" },
  },
}

Wrong LSP Server¶

Check active servers:

:LspInfo

Disable unwanted server:

-- lua/plugins/lsp.lua
return {
  "neovim/nvim-lspconfig",
  opts = {
    servers = {
      tsserver = { enabled = false },
    },
  },
}

LSP Slow or Hanging¶

Check file size and complexity
Exclude large directories from analysis
Increase timeout:

-- lua/plugins/lsp.lua
return {
  "neovim/nvim-lspconfig",
  opts = {
    servers = {
      pyright = {
        settings = {
          python = {
            analysis = {
              diagnosticMode = "openFilesOnly",
            },
          },
        },
      },
    },
  },
}

Python Virtual Environment Not Detected¶

Set path manually:

:PyrightSetPythonPath /path/to/.venv/bin/python

Or configure in pyproject.toml:

[tool.pyright]
venvPath = "."
venv = ".venv"

Treesitter Issues¶

Parser Errors¶

Update parsers:

:TSUpdate

Reinstall specific parser:

:TSInstall! python

Missing Syntax Highlighting¶

Check if parser installed: :TSInstallInfo
Install parser: :TSInstall <language>
Check highlight status: :TSBufToggle highlight

Treesitter Slow¶

Disable for large files:

-- lua/plugins/treesitter.lua
return {
  "nvim-treesitter/nvim-treesitter",
  opts = {
    highlight = {
      disable = function(lang, buf)
        local max_filesize = 100 * 1024  -- 100 KB
        local ok, stats = pcall(vim.loop.fs_stat, vim.api.nvim_buf_get_name(buf))
        if ok and stats and stats.size > max_filesize then
          return true
        end
      end,
    },
  },
}

Keybinding Issues¶

Keybinding Not Working¶

Check if keymap exists:

:Telescope keymaps

Or search directly:

:verbose nmap <leader>f

Keybinding Conflict¶

List all mappings for a key:

:verbose map <key>

Which-key Not Showing¶

Press key and wait (default 300ms). Adjust timeout:

-- lua/config/options.lua
vim.opt.timeoutlen = 500

Display Issues¶

Icons Not Displaying¶

Install a Nerd Font:

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

Configure terminal to use the font.

Colors Wrong¶

Enable true colors:

-- lua/config/options.lua
vim.opt.termguicolors = true

Check terminal supports true color:

echo $TERM  # Should include 256color or truecolor

Cursor Shape Not Changing¶

Set cursor shape in terminal settings or:

-- lua/config/options.lua
vim.opt.guicursor = "n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50"

Performance Issues¶

Slow Startup¶

Profile startup:

:Lazy profile

Identify slow plugins and lazy-load them:

return {
  "slow-plugin",
  event = "VeryLazy",  -- Load after startup
}

Slow Editing¶

Disable heavy features:

-- lua/plugins/disabled.lua
return {
  { "echasnovski/mini.animate", enabled = false },
}

Reduce update frequency:

-- lua/config/options.lua
vim.opt.updatetime = 300

High CPU Usage¶

Check running LSP servers:

:LspInfo

Disable diagnostics temporarily:

:lua vim.diagnostic.disable()

Common Error Messages¶

"module not found"¶

Plugin not installed. Run:

:Lazy sync

"Invalid character"¶

Likely copy-paste issue with special characters. Check for: - Smart quotes instead of regular quotes - Non-breaking spaces - Hidden Unicode characters

"E5108: Error executing lua"¶

Syntax error in Lua config. Check:

:lua require("plugins.myconfig")

"No information available"¶

LSP not attached. Check:

:LspInfo

Reset Configuration¶

Soft Reset¶

Remove plugin state:

rm -rf ~/.local/share/nvim
rm -rf ~/.local/state/nvim
rm -rf ~/.cache/nvim

Hard Reset¶

Backup and remove everything:

mv ~/.config/nvim ~/.config/nvim.bak
mv ~/.local/share/nvim ~/.local/share/nvim.bak

Then reinstall LazyVim:

git clone https://github.com/LazyVim/starter ~/.config/nvim

Getting Help¶

Documentation¶

:help <topic>
:Telescope help_tags

LazyVim Resources¶

Debug Output¶

Enable verbose logging:

nvim -V10log.txt

Check the log file after reproducing the issue.