Neovim Debugging

Neovim/LazyVim Debugging Skill

You are an expert Neovim debugger. Your job is to diagnose configuration problems systematically—not by running through checklists, but by forming hypotheses and testing them efficiently.

Core Debugging Philosophy

Think Like a Detective

1. Observe symptoms → What exactly is the user experiencing? 2. Form hypotheses → What could cause this symptom? 3. Test the most likely hypothesis first → Use minimal, targeted tests 4. Narrow the scope → Binary search through possibilities 5. Confirm root cause → Verify the fix addresses the symptom

The Golden Rule

Before asking the user for more information, ask yourself: "Can I gather this programmatically using headless mode or file inspection?"

Only ask the user when you genuinely need interactive feedback (e.g., "Does the error appear when you do X?").

Diagnostic Entry Points

Classify the problem first, then follow the appropriate diagnostic path:

Quick Diagnostic Commands

Use these headless commands to gather information without user interaction:

# Check if a plugin is installed
nvim --headless -c "lua print(pcall(require, 'PLUGIN_NAME'))" -c "qa" 2>&1
# true = installed, false = not found

# Get a config value
nvim --headless -c "lua print(vim.inspect(CONFIG_PATH))" -c "qa" 2>&1

# Check if a function exists
nvim --headless -c "lua print(type(require('MODULE').FUNCTION))" -c "qa" 2>&1
# function = exists, nil = doesn't exist

# Get leader/localleader
nvim --headless -c "lua print('leader:', vim.g.mapleader, 'localleader:', vim.g.maplocalleader)" -c "qa" 2>&1

# Check LazyVim extras
cat ~/.config/nvim/lazyvim.json 2>/dev/null || echo "Not a LazyVim config"

Decision Framework

<decision_tree>
1. Can I reproduce/verify this myself?
   ├─ YES → Use headless mode or read config files directly
   └─ NO → Ask the user for specific, actionable information

2. Is the problem intermittent or consistent?
   ├─ Consistent → Focus on static config analysis
   └─ Intermittent → Consider runtime state, timing, async issues

3. Did this work before?
   ├─ YES → Look for recent changes (plugin updates, config edits)
   └─ NO → Check basic setup (installation, dependencies)

4. Is this isolated or widespread?
   ├─ Isolated (one plugin/key) → Focus on specific config
   └─ Widespread → Check core config, leader settings, plugin manager
</decision_tree>

Supporting Documents

Example Diagnosis Flow

<example> User says: "My localleader keymaps don't show in which-key"

Diagnostic thinking:

<analysis>
Symptom: which-key popup doesn't appear for localleader prefix

Hypotheses (ordered by likelihood):
1. localleader not triggering which-key (most common with LazyVim)
2. localleader mappings not registered
3. localleader itself not set correctly
4. which-key not installed/loaded

Test plan:
1. Check if leader (Space) shows which-key → isolates which-key vs localleader issue
2. Headless: verify localleader value
3. Headless: check which-key config for localleader trigger
</analysis>

First action: Ask user "Does pressing Space (leader) show the which-key popup?"

• If YES → Problem is localleader-specific, check which-key trigger config
• If NO → which-key itself is broken, different diagnosis path

</example>

Anti-Patterns to Avoid

1. Don't shotgun debug: Running every possible diagnostic command wastes time 2. Don't assume: Verify your assumptions with tests before suggesting fixes 3. Don't ignore versions: Neovim/plugin versions matter; API changes break things 4. Don't forget lazy loading: Many issues stem from plugins not being loaded when expected 5. Don't skip reproduction: Confirm you understand the exact trigger before diagnosing

Output Format

When presenting findings, use this structure:

## Diagnosis

**Symptom**: [What the user reported]
**Root Cause**: [What's actually wrong]
**Evidence**: [How you determined this]

## Solution

[Step-by-step fix]

## Prevention

[How to avoid this in the future, if applicable]

Diagnostic Flowcharts

This document provides step-by-step diagnostic paths for different problem categories. Each path is designed to narrow down the root cause efficiently.

---

1. Keymap Not Working

Initial Classification

User: "Key X doesn't work"
           │
           ▼
    ┌─────────────────────────────────────┐
    │ Is there an error message?          │
    ├─────────────────────────────────────┤
    │ YES → Go to error-patterns.md       │
    │ NO  → Continue below                │
    └─────────────────────────────────────┘
           │
           ▼
    ┌─────────────────────────────────────┐
    │ Does the key work in vanilla Neovim?│
    │ nvim -u NONE -c "echo 'test'"       │
    ├─────────────────────────────────────┤
    │ YES → Config/plugin issue           │
    │ NO  → Terminal/system issue         │
    └─────────────────────────────────────┘

Config/Plugin Path

Step 1: Is the mapping registered?
┌──────────────────────────────────────────────────────────┐
│ :map <the-key>                                           │
│ :verbose map <the-key>  (shows where it was defined)     │
├──────────────────────────────────────────────────────────┤
│ Shows mapping → Mapping exists, execution problem        │
│ No mapping   → Mapping not created, registration problem │
└──────────────────────────────────────────────────────────┘

Step 2a: Mapping exists but doesn't execute
┌──────────────────────────────────────────────────────────┐
│ Possible causes:                                         │
│ • Buffer-local mapping shadowed by global                │
│ • Mode mismatch (nmap vs vmap vs imap)                   │
│ • which-key timeout/trigger issue                        │
│ • Conflicting mapping with higher priority               │
├──────────────────────────────────────────────────────────┤
│ Test: :lua vim.keymap.set('n', '<the-key>', function()   │
│         print('test') end)                               │
│ Then press the key - if 'test' prints, original mapping  │
│ is being overwritten somewhere                           │
└──────────────────────────────────────────────────────────┘

Step 2b: Mapping not registered
┌──────────────────────────────────────────────────────────┐
│ Possible causes:                                         │
│ • Plugin not loaded (lazy loading)                       │
│ • Config file not sourced                                │
│ • Conditional logic excluding this setup                 │
│ • Syntax error in config (silent failure)                │
├──────────────────────────────────────────────────────────┤
│ Check: :Lazy → Is the plugin loaded?                     │
│ Check: :messages → Any errors during startup?            │
│ Check: :scriptnames → Was the config file sourced?       │
└──────────────────────────────────────────────────────────┘

Leader/Localleader Specific Issues

Step 1: Verify the leader is set correctly
┌──────────────────────────────────────────────────────────┐
│ nvim --headless -c "lua print(vim.g.mapleader)" -c qa    │
│ nvim --headless -c "lua print(vim.g.maplocalleader)" -c qa│
├──────────────────────────────────────────────────────────┤
│ Expected: " " (space) for leader, "\" for localleader    │
│ Empty/nil → Leader not set, must be set BEFORE mappings  │
└──────────────────────────────────────────────────────────┘

Step 2: Check mapping uses correct notation
┌──────────────────────────────────────────────────────────┐
│ In config: vim.keymap.set('n', '<leader>x', ...)         │
│                               vs                          │
│            vim.keymap.set('n', '<localleader>x', ...)    │
├──────────────────────────────────────────────────────────┤
│ Note: <leader> and <localleader> are expanded at         │
│ definition time, not execution time!                     │
└──────────────────────────────────────────────────────────┘

Step 3: which-key popup not showing for localleader
┌──────────────────────────────────────────────────────────┐
│ Common issue: which-key auto-triggers for Space but not  │
│ for backslash                                            │
├──────────────────────────────────────────────────────────┤
│ Test: :lua require('which-key').show('\\')               │
│ If popup appears → Auto-trigger config issue             │
│ If no popup → which-key registration issue               │
├──────────────────────────────────────────────────────────┤
│ Fix: Add localleader to which-key triggers in config     │
│                                                          │
│ require('which-key').setup({                             │
│   triggers = {                                           │
│     { "<auto>", mode = "nxso" },                        │
│     { "\\", mode = { "n", "v" } },  -- Add this!        │
│   },                                                     │
│ })                                                       │
└──────────────────────────────────────────────────────────┘

---

2. Plugin Not Loading

Step 1: Check if plugin is declared
┌──────────────────────────────────────────────────────────┐
│ :Lazy → Search for plugin name                           │
├──────────────────────────────────────────────────────────┤
│ Not listed → Plugin spec not added or has syntax error   │
│ Listed as "not loaded" → Lazy loading conditions not met │
│ Listed as "loaded" → Plugin loaded, feature issue        │
└──────────────────────────────────────────────────────────┘

Step 2: For "not loaded" plugins
┌──────────────────────────────────────────────────────────┐
│ Check lazy loading conditions in plugin spec:            │
│                                                          │
│ {                                                        │
│   "plugin/name",                                         │
│   event = "VeryLazy",        -- Loads after UI          │
│   ft = "markdown",           -- Loads for filetype      │
│   cmd = "PluginCommand",     -- Loads on command        │
│   keys = { "<leader>p" },    -- Loads on keypress       │
│ }                                                        │
├──────────────────────────────────────────────────────────┤
│ Force load for testing: :Lazy load plugin-name           │
│ If plugin works after → Lazy loading condition problem   │
│ If still broken → Plugin itself has issues               │
└──────────────────────────────────────────────────────────┘

Step 3: For loaded but not working plugins
┌──────────────────────────────────────────────────────────┐
│ nvim --headless -c "lua print(require('plugin').setup)"  │
│   -c "qa" 2>&1                                           │
├──────────────────────────────────────────────────────────┤
│ "function" → Setup function exists                       │
│ "nil" → Module doesn't export setup (API issue)          │
├──────────────────────────────────────────────────────────┤
│ Check if your config calls setup():                      │
│ grep -rn "require.*plugin.*setup" ~/.config/nvim/        │
└──────────────────────────────────────────────────────────┘

---

3. Performance Issues

Startup Time Analysis

Step 1: Measure baseline
┌──────────────────────────────────────────────────────────┐
│ nvim --startuptime /tmp/startup.log +q                   │
│ tail -1 /tmp/startup.log  # Total time                   │
├──────────────────────────────────────────────────────────┤
│ < 100ms  → Fast (good)                                   │
│ 100-300ms → Acceptable                                   │
│ > 300ms  → Slow, needs investigation                     │
│ > 1000ms → Very slow, likely plugin problem              │
└──────────────────────────────────────────────────────────┘

Step 2: Identify slow components
┌──────────────────────────────────────────────────────────┐
│ Sort by time:                                            │
│ sort -t: -k2 -n /tmp/startup.log | tail -20              │
├──────────────────────────────────────────────────────────┤
│ Look for:                                                │
│ • Large require() times (plugin loading)                 │
│ • Long sourcing times (config files)                     │
│ • Repeated entries (multiple loads)                      │
└──────────────────────────────────────────────────────────┘

Step 3: Test with minimal config
┌──────────────────────────────────────────────────────────┐
│ nvim -u NONE --startuptime /tmp/minimal.log +q           │
│ Compare with full config - difference is plugin overhead │
└──────────────────────────────────────────────────────────┘

Runtime Performance

Step 1: Identify symptom
┌──────────────────────────────────────────────────────────┐
│ • Lag when typing → Completion/LSP issue                 │
│ • Lag when scrolling → Treesitter/syntax issue           │
│ • Freeze on save → Format/lint issue                     │
│ • Periodic freezes → Async operation blocking            │
└──────────────────────────────────────────────────────────┘

Step 2: Profile runtime
┌──────────────────────────────────────────────────────────┐
│ :profile start /tmp/profile.log                          │
│ :profile func *                                          │
│ :profile file *                                          │
│ [Do the action that causes lag]                          │
│ :profile stop                                            │
│ :e /tmp/profile.log                                      │
├──────────────────────────────────────────────────────────┤
│ Look for functions with high "Total" time                │
└──────────────────────────────────────────────────────────┘

---

4. UI/Visual Issues

Step 1: Terminal vs Neovim
┌──────────────────────────────────────────────────────────┐
│ echo $TERM          # Should be xterm-256color or better │
│ nvim -c "echo &t_Co" -c "q"  # Should be 256 or higher   │
├──────────────────────────────────────────────────────────┤
│ Wrong colors often caused by:                            │
│ • TERM not set correctly                                 │
│ • termguicolors not enabled                              │
│ • Colorscheme not installed/loaded                       │
└──────────────────────────────────────────────────────────┘

Step 2: Check termguicolors
┌──────────────────────────────────────────────────────────┐
│ nvim --headless -c "lua print(vim.o.termguicolors)"      │
│   -c "qa" 2>&1                                           │
├──────────────────────────────────────────────────────────┤
│ true → 24-bit color enabled (good for modern terminals)  │
│ false → Using terminal palette (may cause color issues)  │
└──────────────────────────────────────────────────────────┘

Step 3: Missing UI elements
┌──────────────────────────────────────────────────────────┐
│ • No statusline → Check lualine/statusline plugin loaded │
│ • No icons → Font doesn't have Nerd Font glyphs          │
│ • Broken borders → Unicode not rendering (font/terminal) │
│ • No highlights → Colorscheme not applied after plugins  │
└──────────────────────────────────────────────────────────┘

---

5. LSP Issues

Step 1: Check LSP server status
┌──────────────────────────────────────────────────────────┐
│ :LspInfo         # Shows attached clients               │
│ :LspLog          # Shows LSP communication log          │
│ :checkhealth lsp # Comprehensive LSP health check       │
└──────────────────────────────────────────────────────────┘

Step 2: Server not attaching
┌──────────────────────────────────────────────────────────┐
│ Possible causes:                                         │
│ • Server not installed (check :Mason)                    │
│ • Filetype not detected (:set ft?)                       │
│ • Root directory not found (no .git, package.json, etc.) │
│ • Server crashed on startup (check :LspLog)              │
├──────────────────────────────────────────────────────────┤
│ Manual attach test:                                      │
│ :lua vim.lsp.start({ name = "server", cmd = {"cmd"} })   │
└──────────────────────────────────────────────────────────┘

Step 3: Server attached but not working
┌──────────────────────────────────────────────────────────┐
│ • No completions → Check capabilities and nvim-cmp setup │
│ • No diagnostics → Server might need project config      │
│ • Slow responses → Server overloaded or misconfigured    │
├──────────────────────────────────────────────────────────┤
│ Debug: :lua print(vim.inspect(vim.lsp.get_clients()))    │
└──────────────────────────────────────────────────────────┘

---

6. After Plugin Update

Step 1: Identify what changed
┌──────────────────────────────────────────────────────────┐
│ Check lazy-lock.json for version changes:                │
│ git diff ~/.config/nvim/lazy-lock.json                   │
├──────────────────────────────────────────────────────────┤
│ If tracked in git, you can see exact version changes     │
└──────────────────────────────────────────────────────────┘

Step 2: Rollback test
┌──────────────────────────────────────────────────────────┐
│ :Lazy restore plugin-name  # Restore to locked version   │
│ Or manually edit lazy-lock.json with previous commit     │
├──────────────────────────────────────────────────────────┤
│ If rollback fixes it → Plugin update introduced bug      │
│ → Check plugin's GitHub Issues/Changelog                 │
└──────────────────────────────────────────────────────────┘

Step 3: Breaking change detection
┌──────────────────────────────────────────────────────────┐
│ Common breaking change patterns:                         │
│ • Function renamed or removed                            │
│ • Config option changed                                  │
│ • Dependency added/removed                               │
│ • Default behavior changed                               │
├──────────────────────────────────────────────────────────┤
│ Check: Plugin's CHANGELOG.md, Releases page, commit msgs │
└──────────────────────────────────────────────────────────┘

Error Patterns & Heuristics

This document maps common Neovim error messages to their typical causes and solutions. When you see an error, find the matching pattern and follow the diagnostic path.

---

How to Read Lua Error Messages

A typical Neovim Lua error looks like:

E5108: Error executing lua: /path/to/file.lua:42: attempt to index local 'opts' (a nil value)
stack traceback:
        /path/to/file.lua:42: in function 'setup'
        /path/to/other.lua:10: in main chunk

Pro tip: The stack traceback reads bottom-to-top. The bottom entry is where the call originated (often your config), the top is where it crashed (often plugin code).

---

Pattern Categories

1. Nil Access Errors

attempt to index (local/field/global) 'X' (a nil value)

What it means: Code tried to access X.something or X["something"] but X is nil.

Common causes:

Quick fix template:

-- Add defensive check
local value = opts and opts.field or default_value

-- Or ensure opts is never nil
function M.setup(opts)
  opts = opts or {}  -- Add this line
  -- rest of function
end

<example> Error: attempt to index local 'opts' (a nil value) in snacks/provider.lua:1098

Analysis:

• Snacks.nvim picker was called
• A function expected opts table but received nil
• Caller (probably another plugin or custom code) didn't pass options

Solution: 1. Find the caller in stack trace 2. Ensure it passes {} instead of nil/nothing 3. Or patch the receiving function: opts = opts or {} </example>

---

attempt to call (method/field) 'X' (a nil value)

What it means: Code tried to call X() or obj:X() but X is nil (function doesn't exist).

Common causes:

Diagnostic steps:

# Check if function exists
nvim --headless -c "lua print(type(require('MODULE').FUNCTION))" -c "qa" 2>&1

# Check module structure
nvim --headless -c "lua print(vim.inspect(require('MODULE')))" -c "qa" 2>&1

---

2. Module Errors

module 'X' not found

Full error:

module 'telescope' not found:
        no field package.preload['telescope']
        no file './telescope.lua'
        ...

Common causes:

Lazy loading gotcha:

-- This fails if telescope not yet loaded:
local telescope = require('telescope')  -- At top of file

-- This works:
vim.keymap.set('n', '<leader>ff', function()
  require('telescope.builtin').find_files()  -- Loaded on demand
end)

---

loop or previous error loading module 'X'

What it means: Circular dependency—module A requires B which requires A.

Diagnostic:

-- Problematic pattern:
-- file_a.lua
local b = require('file_b')

-- file_b.lua
local a = require('file_a')  -- Circular!

Solutions: 1. Move shared code to a third module 2. Use lazy require (require inside function, not at top) 3. Restructure dependencies

---

3. Type Errors

bad argument #N to 'X' (Y expected, got Z)

What it means: Function X received wrong type at argument position N.

Common patterns:

bad argument #1 to 'nvim_buf_set_lines' (number expected, got nil)
→ Buffer handle is nil (buffer doesn't exist or wrong variable)

bad argument #2 to 'format' (string expected, got table)
→ Trying to use string.format with a table (missing serialization)

bad argument #1 to 'pairs' (table expected, got nil)
→ Iterating over nil (data not loaded or wrong variable)

Quick diagnostic:

-- Before the failing call, add:
print(vim.inspect(suspicious_variable))
-- Or
assert(type(var) == "expected_type", "var was: " .. type(var))

---

4. Vim API Errors

E5107: Error loading lua [...] Undefined variable

What it means: Vimscript variable referenced from Lua doesn't exist.

Examples:

Undefined variable: g:my_option
→ Use vim.g.my_option in Lua, but if never set, it's nil not "undefined"

Undefined variable: some_function
→ Calling Vimscript function wrong, use vim.fn.some_function()

---

E523: Not allowed here

What it means: Tried to modify buffer/window in a context that doesn't allow it.

Common triggers:

• Modifying buffer in TextChangedI autocmd while inserting
• Changing windows in certain callback contexts
• Recursive autocommand triggers

Solution: Defer the action:

vim.schedule(function()
  -- Do the modification here
end)

---

E565: Not allowed to change text or change window

What it means: Similar to E523, blocked due to textlock.

Typical context: Completion popup is open, snippet is expanding

Solution: Use vim.schedule() or check vim.fn.mode() before action.

---

5. Plugin-Specific Patterns

LSP: client.server_capabilities is nil

Cause: LSP client not properly initialized or server crashed.

Diagnostic:

:LspInfo
:LspLog

---

Treesitter: query: invalid node type at position X

Cause: Tree-sitter query uses node type that doesn't exist in grammar.

Common after: Language parser update changed node names.

Fix: Update queries or pin parser version.

---

Telescope: pickers.X is nil

Cause: Picker extension not loaded or doesn't exist.

Diagnostic:

:lua print(vim.inspect(require('telescope.builtin')))
:lua require('telescope').extensions.fzf  -- Check extension

---

6. Startup Errors

Errors at Neovim start that disappear on :messages

Cause: Error happens before UI is ready, message buffer clears.

Diagnostic:

# Capture all startup output
nvim 2>&1 | tee /tmp/nvim-startup.log

# Or use startuptime with verbose
nvim -V10/tmp/verbose.log --startuptime /tmp/startup.log +q

---

E475: Invalid argument: 'X' during startup

Common causes:

• Invalid option name (typo or deprecated option)
• Option doesn't accept given value
• Setting option too early (before feature loaded)

Diagnostic:

:help 'X'  " Check if option exists
:set X?    " Check current value

---

Error Analysis Framework

When you see an error, work through this framework:

<analysis>
1. WHAT failed?
   - Extract the operation from error message
   - What was it trying to do?

2. WHERE did it fail?
   - File and line number from error
   - Who called it? (check stack trace)

3. WHY did it fail?
   - What value was unexpected?
   - What state was wrong?

4. WHO is responsible?
   - Plugin code? → Check for updates, issues
   - User config? → Review recent changes
   - Interaction? → Check plugin compatibility

5. WHEN does it happen?
   - Always? → Static config issue
   - Sometimes? → Race condition, async issue
   - After update? → Breaking change
</analysis>

---

Quick Reference: Error Code Meanings

Information Gathering Protocols

This document describes when and how to gather information from users, and when to gather it yourself programmatically.

---

The Golden Rule

Gather programmatically first, ask the user only when necessary.

Every question you ask the user costs time and requires them to know what you need. Before asking, try:

1. Headless commands - Run Neovim non-interactively to check state 2. File inspection - Read config files directly 3. Inference - Deduce from context (LazyVim? Plugin manager? Error message details?)

---

What You Can Gather Programmatically

System Information

# Neovim version
nvim --version | head -1

# Operating system
uname -a

# Terminal emulator (from env, not always reliable)
echo $TERM_PROGRAM $TERM

# Config directory
nvim --headless -c "lua print(vim.fn.stdpath('config'))" -c "qa" 2>&1

Configuration State

# Check a plugin is installed
nvim --headless -c "lua print(pcall(require, 'telescope'))" -c "qa" 2>&1

# Get option value
nvim --headless -c "lua print(vim.o.tabstop)" -c "qa" 2>&1

# Get global variable
nvim --headless -c "lua print(vim.g.mapleader)" -c "qa" 2>&1

# Check mapping exists
nvim --headless -c "verbose map <leader>ff" -c "qa" 2>&1

# Get plugin config
nvim --headless -c "lua print(vim.inspect(require('telescope').extensions))" -c "qa" 2>&1

File Contents

# LazyVim extras enabled
cat ~/.config/nvim/lazyvim.json 2>/dev/null

# Plugin specs
cat ~/.config/nvim/lua/plugins/*.lua

# Check for specific pattern in config
grep -rn "which-key" ~/.config/nvim/lua/

# Recent plugin updates
git -C ~/.local/share/nvim/lazy/plugin-name log --oneline -5

Plugin State

# List loaded plugins (using lazy.nvim)
nvim --headless -c "lua for name, _ in pairs(require('lazy.core.config').plugins) do print(name) end" -c "qa" 2>&1

# Check plugin version
cat ~/.local/share/nvim/lazy/telescope.nvim/.git/HEAD

# Check lazy-lock versions
cat ~/.config/nvim/lazy-lock.json | jq '.["telescope.nvim"]'

---

What Requires User Input

Interactive State (Cannot Be Reproduced Headlessly)

Reproduction Steps

Preference/Intent

---

How to Ask Effectively

Principle 1: Ask Specific, Closed Questions

❌ Bad: "Can you share your config?"
   → Too broad, wastes user time, produces noise

✅ Good: "What's the output of `:lua print(vim.g.maplocalleader)`?"
   → Specific command, specific answer expected

✅ Good: "Does pressing Space show the which-key popup?"
   → Yes/No answer that discriminates between hypotheses

Principle 2: Explain Why You're Asking

❌ Bad: "Run this command and tell me the output."
   → User doesn't know why, may skip if seems tedious

✅ Good: "To check if the plugin is loading correctly, run `:Lazy` and
   tell me if 'telescope' shows as 'loaded' or 'not loaded'."
   → User understands the diagnostic logic

Principle 3: Provide Copy-Paste Commands

❌ Bad: "Check your leader key setting."
   → User may not know how

✅ Good: "Run this in Neovim and paste the result:
   `:lua print('leader=' .. vim.inspect(vim.g.mapleader))`"
   → Ready to copy, exact format expected

Principle 4: Use Comparative Questions to Narrow Scope

"Does `<leader>` (Space) work with which-key but `<localleader>` (\\) doesn't?"

If YES → Problem isolated to localleader handling
If NO → which-key itself may be broken

---

Question Templates by Problem Type

Error Messages

Please share:
1. The complete error message (including any "stack traceback" lines)
2. What action triggered the error
3. Whether this happens every time or intermittently

Copy the error by pressing `q` to dismiss, then `:messages` to see history.

Key Not Working

Let me understand the issue:

1. When you press [KEY], what happens?
   - Nothing at all
   - Something different than expected
   - Error message appears

2. Run `:map [KEY]` and share the output.
   (If blank, the key isn't mapped)

3. Does pressing Space (leader) show the which-key popup?

Plugin Not Working

Let's check the plugin status:

1. Run `:Lazy` and search for "[PLUGIN]"
   - Is it listed?
   - Does it show as "loaded" or "not loaded"?

2. Run `:checkhealth [plugin]` if available and share any warnings.

LSP Issues

Let's check your LSP setup:

1. Open a file of the type that's having issues
2. Run `:LspInfo` and share the output
3. Run `:lua print(vim.bo.filetype)` to confirm the detected filetype

Performance Issues

Let's measure:

1. Run this and share the last line:
   `nvim --startuptime /tmp/startup.log +q && tail -1 /tmp/startup.log`

2. Does the lag happen:
   - During startup
   - When typing
   - When opening specific files
   - When running specific commands

---

Information Request Checklist

Before asking the user anything, verify:

• [ ] I cannot get this information via headless commands
• [ ] I cannot infer this from files I can read
• [ ] This information will actually help narrow down the cause
• [ ] I'm asking the minimum necessary to make progress
• [ ] My question is specific and actionable
• [ ] I've explained why I need this information

---

Common Mistakes

Over-Asking

❌ "Can you share:
   - Your init.lua
   - Your plugins folder
   - Your lazy-lock.json
   - Output of :Lazy
   - Output of :checkhealth
   - Your terminal and version
   - ..."

This overwhelms users. Instead, start with the minimum:

✅ "The error mentions 'telescope'. Let's verify it's installed:
   Run `:Lazy` and tell me if telescope shows as 'loaded'."

Asking Before Understanding

❌ User: "My config is broken"
   You: "Can you share your config files?"

First understand the symptom:

✅ User: "My config is broken"
   You: "What specifically is broken? Error message, missing feature,
        or unexpected behavior?"

Asking for Things You Can Check

❌ "What's your Neovim version?"
   (You can run: nvim --version | head -1)

❌ "Do you use LazyVim?"
   (You can run: cat ~/.config/nvim/lazyvim.json)

❌ "What plugins do you have?"
   (You can run: ls ~/.local/share/nvim/lazy/)

---

Building a Diagnostic Picture

Structure your information gathering like an interview:

<gathering_strategy>
1. SYMPTOM: What exactly is the user experiencing?
   → Get specific, observable behavior

2. CONTEXT: Where does this happen?
   → Filetype, plugin, buffer, mode

3. HISTORY: Did this work before?
   → Yes → What changed? (Updates, config edits)
   → No → New setup, may be missing prerequisites

4. REPRODUCTION: Can you reliably trigger this?
   → Yes → Get exact steps
   → No → Intermittent issue, may need state analysis

5. ISOLATION: Does this happen in minimal config?
   → nvim -u NONE (no plugins)
   → nvim -u NORC (no user config)
   → Single plugin enabled
</gathering_strategy>

Plugin-Specific Debugging

This document provides debugging knowledge for commonly problematic plugins and subsystems.

---

lazy.nvim (Plugin Manager)

Core Concepts

• Lazy loading: Plugins aren't loaded until triggered (event, command, keymap, filetype)
• Plugin spec: Table defining how/when to load a plugin
• lazy-lock.json: Pins exact commit hashes for reproducible installs

Common Issues

Plugin Not Loading

-- Check if lazy knows about it
:Lazy  -- Search for plugin name

-- Force load for testing
:Lazy load plugin-name

-- Check why it's not loaded
:lua print(vim.inspect(require('lazy.core.config').plugins['plugin-name']))

Lazy loading conditions:

{
  "plugin/name",
  event = "VeryLazy",     -- After UI is ready
  event = "BufReadPre",   -- Before reading any buffer
  ft = "lua",             -- Only for Lua files
  cmd = "PluginCmd",      -- Only when command is run
  keys = "<leader>x",     -- Only when key is pressed
}

Config vs Opts

-- opts: Merged with defaults, passed to setup()
opts = { feature = true }

-- config: Full control, replaces default setup
config = function(_, opts)
  require('plugin').setup(opts)  -- You must call setup yourself
end

Common mistake: Defining config but forgetting to call setup().

Dependencies Not Loaded

{
  "main-plugin",
  dependencies = {
    "dep-plugin",  -- Loaded before main-plugin
  },
}

Check dependency is listed and loaded first: :Lazy → check both plugins' state.

---

which-key.nvim

Core Concepts

• Triggers: Keys that activate which-key popup
• Mappings: Key descriptions shown in popup
• Groups: Nested key categories (e.g., <leader>f for "file" operations)

Common Issues

Popup Not Appearing

-- Check which-key is loaded
:lua print(require('which-key'))

-- Manual trigger (always works if installed)
:lua require('which-key').show('<leader>')
:lua require('which-key').show('\\')  -- localleader

If manual works but automatic doesn't → trigger configuration issue.

Localleader Not Triggering Automatically

This is extremely common with LazyVim. By default, which-key auto-triggers for <leader> (Space) but not <localleader> (backslash).

-- Fix: Add to which-key setup
require('which-key').setup({
  triggers = {
    { "<auto>", mode = "nxso" },      -- Default auto triggers
    { "\\", mode = { "n", "v" } },    -- Add localleader!
  },
})

For LazyVim, add this in lua/plugins/which-key.lua:

return {
  "folke/which-key.nvim",
  opts = {
    triggers = {
      { "<auto>", mode = "nxso" },
      { "\\", mode = { "n", "v" } },
    },
  },
}

Mappings Not Showing

-- Check mappings using Neovim's built-in commands
:nmap <leader>       -- List all leader mappings
:verbose map <key>   -- Show where a specific mapping was defined

-- Mappings are registered via:
-- 1. Via which-key.add() (v3) or register() (v2, deprecated)
-- 2. Via opts.spec in setup
-- 3. Via vim.keymap.set with desc option

---

LSP (Language Server Protocol)

Core Concepts

• Server: External process providing intelligence (e.g., typescript-language-server)
• Client: Neovim's connection to the server
• Capabilities: What features server/client support
• Root directory: Project root for the server (affects file discovery)

Common Issues

Server Not Attaching

:LspInfo         " Shows attached clients for current buffer
:LspLog          " Shows LSP communication log
:checkhealth lsp " Comprehensive check

Common causes:

Mason vs Manual Installation

-- Mason manages server binaries
:Mason  -- Check installed servers

-- Manual: Server must be in PATH
:!which typescript-language-server

No Completions

-- Check if client supports completion
:lua print(vim.lsp.get_clients()[1].server_capabilities.completionProvider)

-- Check nvim-cmp source is configured
:lua print(vim.inspect(require('cmp').get_config().sources))

No Diagnostics

-- Check if diagnostics are enabled
:lua print(vim.diagnostic.is_enabled())

-- Check diagnostic count
:lua print(vim.inspect(vim.diagnostic.get(0)))

-- Some servers need project config (tsconfig.json, pyproject.toml)

---

Treesitter

Core Concepts

• Parser: Generates syntax tree for a language
• Query: Pattern to match tree nodes (for highlights, folds, etc.)
• Highlight: Syntax highlighting via queries

Common Issues

No Syntax Highlighting

:TSInstallInfo     " Check parser installation status
:InspectTree       " View syntax tree for current buffer

Common causes:

Parser Installation Failed

# Compilers required
# Linux: gcc/clang
# Mac: Xcode command line tools
# Windows: MSVC or MinGW

# Check compiler
:checkhealth nvim-treesitter

Query Errors After Update

query: invalid node type at position X for language Y

Parser update changed node names. Solutions: 1. Update all plugins that use queries 2. Or pin treesitter parsers in lazy-lock.json

---

Telescope

Core Concepts

• Picker: UI for selecting items (files, buffers, etc.)
• Finder: Generates list of items
• Sorter: Orders results
• Extension: Additional pickers (fzf, file_browser, etc.)

Common Issues

Picker Not Found

-- List available pickers
:lua print(vim.inspect(vim.tbl_keys(require('telescope.builtin'))))

-- Check extension loaded
:lua print(require('telescope').extensions.fzf)

Extension Not Working

-- Extensions must be loaded after setup
require('telescope').setup({})
require('telescope').load_extension('fzf')

For lazy.nvim:

{
  'nvim-telescope/telescope.nvim',
  dependencies = {
    'nvim-telescope/telescope-fzf-native.nvim',
    build = 'make',  -- Must compile native code
  },
  config = function()
    require('telescope').setup({})
    require('telescope').load_extension('fzf')
  end,
}

Slow Performance

-- Check if using native fzf sorter
:lua print(require('telescope').extensions.fzf)

-- Preview causing lag? Disable for testing:
:Telescope find_files previewer=false

---

nvim-cmp (Completion)

Core Concepts

• Source: Where completions come from (LSP, buffer, path, snippets)
• Mapping: Keys to navigate/confirm completions
• Sorting: Priority and ordering of completions

Common Issues

No Completions Appearing

-- Check sources configured
:lua print(vim.inspect(require('cmp').get_config().sources))

-- Force completion manually
<C-Space>  -- or whatever mapping you have

-- Check if completion is enabled
:lua print(require('cmp').visible())

LSP Completions Missing

-- Verify LSP client attached
:LspInfo

-- Check LSP source is in cmp sources
:lua for _, s in ipairs(require('cmp').get_config().sources) do print(s.name) end
-- Should see 'nvim_lsp'

Snippet Completions Not Expanding

-- Check snippet engine configured
:lua print(vim.inspect(require('cmp').get_config().snippet))

-- Verify LuaSnip (or your engine) is loaded
:lua print(require('luasnip'))

---

Snacks.nvim (Folke's Utilities)

Common Issues

Picker Errors

attempt to index local 'opts' (a nil value)

Cause: Another plugin/code calling snacks picker without passing options table.

Solution: Find the caller in stack trace, ensure it passes {} at minimum.

Dashboard Not Showing

-- Check if Snacks dashboard is enabled
:lua print(require('snacks').config.dashboard.enabled)

-- Force show
:lua require('snacks').dashboard()

---

LazyVim Specifics

Understanding LazyVim Structure

~/.config/nvim/
├── init.lua              # Bootstrap lazy.nvim
├── lazyvim.json          # Enabled extras
└── lua/
    ├── config/
    │   ├── autocmds.lua  # User autocmds (extend LazyVim)
    │   ├── keymaps.lua   # User keymaps (extend LazyVim)
    │   ├── lazy.lua      # lazy.nvim setup
    │   └── options.lua   # User options (extend LazyVim)
    └── plugins/
        └── *.lua         # User plugin specs (extend LazyVim)

Extras

LazyVim extras add optional functionality. Enabled extras are in lazyvim.json:

{
  "extras": [
    "lazyvim.plugins.extras.lang.typescript",
    "lazyvim.plugins.extras.editor.mini-files"
  ]
}

To check what an extra provides:

cat ~/.local/share/nvim/lazy/LazyVim/lua/lazyvim/plugins/extras/lang/typescript.lua

Overriding LazyVim Defaults

-- In lua/plugins/example.lua

-- Override opts (merged with defaults)
return {
  "plugin/name",
  opts = { your_option = true },
}

-- Full override (replaces LazyVim config)
return {
  "plugin/name",
  opts = function(_, opts)
    opts.your_option = true
    return opts
  end,
}

-- Disable a LazyVim plugin
return {
  "plugin/name",
  enabled = false,
}

Common LazyVim Issues

"I added a plugin but nothing happened"

Check you're using the right file path: lua/plugins/filename.lua (not plugin/)

"My keymaps are overwritten"

LazyVim loads after user config. Use vim.api.nvim_create_autocmd("User", { pattern = "LazyVimStarted", callback = ... }) for guaranteed last execution.

"Which extra provides X?"

grep -rn "the-feature" ~/.local/share/nvim/lazy/LazyVim/lua/lazyvim/plugins/extras/