Troubleshooting

First Commands To Run

When something breaks, start here:

:checkhealth
:Lazy
:Mason

• :checkhealth reports missing tools and environment problems.
• :Lazy shows plugin install/update/load status.
• :Mason shows language servers and external tools.

Plugin Problems

Open:

:Lazy

Useful actions inside Lazy:

• I: install missing plugins.
• U: update plugins.
• S: sync plugins.
• ?: show Lazy help.

If a plugin was just added, restart Neovim after installation.

LSP Is Not Working

Check whether a language server is attached:

:LspInfo

Then check external tools:

:Mason

Common causes:

• The filetype is not detected correctly.
• No LSP server is configured for that language.
• Mason has not installed the server yet.
• The server needs a project root file such as .git, package.json, pyproject.toml, or Cargo.toml.

Formatting Is Not Working

Manual formatting is:

<space>f

Formatting is configured in lua/kickstart/plugins/conform.lua.

Important details:

• Format on save is intentionally disabled unless a filetype is added to enabled_filetypes.
• External formatters must be configured under formatters_by_ft.
• If no external formatter is configured, Conform can fall back to LSP formatting.

Use this command for formatter details:

:ConformInfo

Telescope Native FZF Did Not Build

telescope-fzf-native.nvim is built with make, but only if make is available.

Check your system:

make --version

If it is missing, install build tools for your platform and run :Lazy build or :Lazy sync.

Treesitter Parser Problems

Treesitter installs parsers when the tree-sitter executable is available.

Check:

tree-sitter --version

Inside Neovim, update parsers with:

:TSUpdate

If highlighting is strange for one language, open :checkhealth and inspect the Treesitter section.

Icons Look Wrong

This config has:

vim.g.have_nerd_font = false

If you use a Nerd Font in your terminal, set it to true in init.lua.

If icons still look wrong, make sure the terminal profile itself is using the Nerd Font, not only the system font picker.

Search Does Not Find Text

Project search uses external grep tooling through Telescope. If <space>sg does not work well, check that rg is installed:

rg --version

The builtin current-buffer search <space>/ should still work even without project grep.

Recovering From Config Errors

If Neovim errors during startup, open it without loading this config:

nvim --clean

Then inspect the recent change. Useful files to check first:

• init.lua
• lua/lazy-plugins.lua
• the plugin file you last edited under lua/kickstart/plugins/
• lua/custom/plugins/init.lua

For Lua syntax checks, open the file and run:

:luafile %