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 nvim-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:
["<Tab>"] = 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 <leader>ff       → check what's bound to this key
:verbose map <leader>ff → show where the mapping was set

Fix: find the conflict and vim.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

What's Next​