Neovim Fix, Crash & Optimization Guide

Neovim is a fork of Vim focused on extensibility and a first-class Lua scripting API. It runs in a terminal and on Windows/macOS/Linux, and is commonly used with a plugin manager, Treesitter highlighting, and the built-in LSP client. This guide covers real, common Neovim problems.

Install / First Setup

Neovim is a native binary invoked as nvim. Prefer a recent release (0.9+) for the LSP and Treesitter features below.

Windows

scoop install neovim
# or: choco install neovim
# or download the zip from github.com/neovim/neovim/releases and add the bin folder to PATH

macOS

brew install neovim

Linux (Debian/Ubuntu)

sudo apt install neovim
# the distro package can be old; for the latest, use the AppImage or build from source

Your config lives at ~/.config/nvim/init.lua (Linux/macOS) or ~/AppData/Local/nvim/init.lua (Windows). Confirm the path with :echo stdpath('config') inside Neovim.

Common Issues & Fixes

LSP not attaching / "LSP client not started"

Cause: The language server binary isn't installed, the filetype isn't detected, or lspconfig isn't set up for that language. Fix: Run :LspInfo to see which clients are attached. Ensure the server is available — install it system-wide or via Mason (:MasonInstall <server>). Then require it in your config, e.g. require('lspconfig').pyright.setup({}). Make sure the buffer's filetype matches (:set filetype?).

Treesitter parse error / "Error executing lua ... treesitter"

Cause: The parser for the language isn't installed or is out of date. Fix: Install or update parsers with :TSInstall <language> and :TSUpdate. If a specific language errors, remove and reinstall its parser. Neovim 0.9+ manages parsers through nvim-treesitter; ensure that plugin is loaded.

init.lua error on startup / "attempt to call global ..."

Cause: A Lua syntax error or a plugin require failing before it's available. Fix: Read the error message — it names the file and line. Run :checkhealth for a full diagnostic summary of providers, LSP, and Treesitter. Common fixes: ensure the plugin is installed before you call it, and that Lua syntax is valid (luafile % to source the file and surface errors).

"module 'packer' not found" / plugin manager missing

Cause: The plugin manager itself isn't installed, so require('packer') or require('lazy') fails. Fix: Install your manager: for packer.nvim clone it into ~/.local/share/nvim/site/pack/packer/start/packer.nvim; for lazy.nvim clone into ~/.local/share/nvim/lazy/lazy.nvim. Then run :PackerSync or :Lazy sync to fetch your plugins.

Mouse or truecolor not working in the terminal

Cause: The terminal doesn't advertise truecolor, or mouse support is off. Fix: Enable set mouse=a in init.lua and ensure your terminal sets $TERM to a 256-color or truecolor value (e.g. xterm-256color). For truecolor add vim.opt.termguicolors = true and confirm your terminal supports it.

Neovim ignores my config / opens like plain Vim

Cause: The config is in the wrong path or the file is named incorrectly. Fix: Neovim reads init.lua (not .vimrc) from the stdpath config dir shown by :echo stdpath('config'). Move your file there, or if you prefer Vimscript use init.vim in the same directory.

Performance & Optimization

• Lazy-load plugins by event/filetype so startup stays fast (lazy.nvim does this by default).
• Keep Treesitter parsers limited to languages you actually edit.
• For very large files, consider disabling Treesitter highlighting or LSP for that buffer to avoid lag.
• Profile startup with nvim --startuptime /tmp/nvim.log and inspect the slowest entries.

Version & Compatibility Notes

Neovim releases are versioned (e.g. 0.9, 0.10) and the Lua API and built-in LSP client have changed across them. Distro packages on some Linux distributions lag behind upstream. For the exact current version and API details, consult the official Neovim documentation and :help.

FAQ

Q: Where does Neovim store its config? A: At ~/.config/nvim/init.lua on Linux/macOS and ~/AppData/Local/nvim/init.lua on Windows. Check the exact path with :echo stdpath('config').

Q: How do I run a health check? A: Run :checkhealth from within Neovim. It reports on the provider, LSP, Treesitter, and other subsystems and points to likely fixes.

Q: Why won't my LSP client attach? A: Usually the language server binary isn't installed or lspconfig isn't set up for that filetype. Run :LspInfo and :checkhealth to see what's missing.

Q: How do I install plugins? A: Use a plugin manager such as lazy.nvim or packer.nvim, declare your plugins in init.lua, then run :Lazy sync or :PackerSync.

Q: Is Neovim compatible with my old .vimrc? A: Mostly. Neovim reads init.vim or init.lua; most Vimscript works, but some legacy options and plugins differ. Migrating to Lua is recommended for new setups.

Related Guides

• Vim Fix & Optimization Guide
• Visual Studio Code Fix & Optimization Guide

Accuracy Note

Commands and paths reflect common, real-world setups as of 2026-08. Always verify against your installed version and OS. When in doubt, consult the official Neovim documentation.