Skip to main content

Common Errors and Fixes

Startup Errors​

"Error detected while processing ~/.config/nvim/init.lua"​

Symptom: Neovim shows Lua errors on startup.

Fix:

# Run headless to see the full error
nvim --headless -c "quit" 2>&1

# Check which file has the error
nvim --startuptime /tmp/startup.log && cat /tmp/startup.log

Common causes:

  • Missing require() file
  • Syntax error in Lua (unmatched {, wrong quotes)
  • Plugin not installed yet (run :Lazy install first)

"module 'X' not found"​

-- Wrong: file doesn't exist or wrong path
require("plugins.doesnt-exist")

-- Fix: check the file path under lua/
-- lua/plugins/doesnt-exist.lua must exist

Plugin Errors​

Plugin Not Loading​

:Lazy                → check status (installed vs not)
:Lazy install        → install missing
:Lazy update         → update all
:Lazy log            → see recent changes

"attempt to call a nil value"​

Usually means a function from a plugin is called before the plugin loaded, or the plugin API changed.

-- Wrong: calling setup before plugin loads
require("telescope").setup({})   -- if telescope isn't installed

-- Fix: wrap in pcall to handle gracefully
local ok, telescope = pcall(require, "telescope")
if not ok then return end
telescope.setup({})

LSP Errors​

LSP Not Attaching​

:LspInfo             → check if LSP is attached to buffer
:checkhealth lsp     → LSP health diagnostics

Common reasons:

  • Language server not installed: :MasonInstall lua-language-server
  • Wrong filetype: :set filetype? — check if it matches
  • Root dir not detected: LSP requires a project root (e.g., package.json, .git)

LSP Very Slow or Freezing​

lua/config/options.lua
-- Reduce update frequency
vim.opt.updatetime = 300   -- default 4000 is too slow

-- Disable for large files
vim.api.nvim_create_autocmd("BufReadPre", {
  callback = function()
    local max = 1024 * 100  -- 100KB
    if vim.fn.getfsize(vim.fn.expand("<afile>")) > max then
      vim.b.large_file = true
      vim.cmd("LspStop")
    end
  end,
})

"LSP request timeout"​

-- Increase timeout in format call
vim.lsp.buf.format({ async = false, timeout_ms = 5000 })

Completion Errors​

No Completions Showing​

  1. Check nvim-cmp is installed: :Lazy → find vim-cmp
  2. Check sources are configured
  3. Check LSP is attached: :LspInfo
  4. Try manually: in Insert mode, press Ctrl+Space

Completion Conflicts with Tab​

Your <Tab> binding may conflict. Use <C-n> and <C-p> as fallback:

-- In nvim-cmp mapping:
["&lt;Tab&gt;"] = cmp.mapping(function(fallback)
  if cmp.visible() then
    cmp.select_next_item()
  else
    fallback()  -- if no completion, use normal Tab
  end
end, { "i", "s" }),

Treesitter Errors​

"treesitter parser X not found" on startup​

:TSInstall python     → install parser
:TSUpdate             → update all

Syntax highlighting looks wrong​

:TSBufToggle highlight   → toggle treesitter highlight
:checkhealth nvim-treesitter

Color and Display Issues​

Colors look wrong / washed out​

lua/config/options.lua
vim.opt.termguicolors = true
~/.tmux.conf
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*256col*:Tc"

Icons showing as boxes or question marks​

Install a Nerd Font in your terminal emulator and set it as the default font. Recommended: JetBrains Mono Nerd Font, FiraCode Nerd Font.

Performance Issues​

Slow startup​

:Lazy profile         → see what takes longest

Fix:

  • Ensure plugins use event, cmd, keys for lazy loading
  • Disable heavy plugins you're not using

Slow while editing​

-- Reduce treesitter sync_install overhead
-- Disable for large files
-- Check if formatOnSave is blocking (use async = true)
vim.lsp.buf.format({ async = true })

Keymap Conflicts​

A keymap does nothing / wrong thing fires​

:map &lt;leader&gt;ff       → check what's bound to this key
:verbose map &lt;leader&gt;ff → show where the mapping was set

Fix: find the conflict and im.keymap.del or reassign.

Diagnostic Commands Summary​

:checkhealth              → overall health check
:checkhealth lsp          → LSP-specific
:checkhealth nvim-treesitter   → treesitter check
:Lazy profile             → startup timing
:LspInfo                  → LSP attachment info
:lua print(vim.inspect(vim.lsp.get_clients()))  → active clients
:verbose set option?      → who set this option
:messages                 → recent Neovim messages

In LazyVim​

LazyVim Context

LazyVim provides several built-in mechanisms to troubleshoot and manage plugins efficiently. It handles lazy loading automatically for most features and provides its own comprehensive health check command to quickly identify issues in your setup.

AspectVanilla NeovimLazyVim
Health Checks:checkhealth:LazyHealth + :checkhealth lazy
Plugin Updates:Lazy updateSame, but LazyVim uses a lazy-lock.json to ensure stability
LSP Info:LspInfo:LspInfo and <leader>cl to see LSP info
Keymap Debugging:verbose mapUses which-key.nvim by default (press <leader> and wait to see all mappings)

Troubleshooting LazyVim Specifically​

  • LazyVim Dashboard Errors: If you see errors on startup, run :LazyHealth to verify that all dependencies (like Nerd Fonts, Git, Ripgrep, etc.) are installed correctly.
  • Overriding Defaults: A common error in LazyVim is trying to configure a plugin by calling equire('plugin').setup() directly. Instead, return a table in lua/plugins/myplugin.lua using the opts key to let LazyVim merge your settings with its defaults safely.
  • Reverting Updates: If an update breaks your configuration, you can use :Lazy restore to rollback plugins to the exact commits recorded in lazy-lock.json.

What's Next​