Troubleshooting

Common issues, solutions, and debugging techniques for nvim-treesitter

This guide covers common issues you might encounter with nvim-treesitter and how to resolve them.

Health Check

The first step in troubleshooting should always be running the health check:

:checkhealth nvim-treesitter

The health check validates:

• Neovim version compatibility (requires 0.11+)
• Tree-sitter ABI version (requires ABI >= 13)
• Required external tools (tree-sitter, curl, tar)
• Installation directory permissions
• Installed parsers and their query files

Run :checkhealth nvim-treesitter after any configuration changes or installation issues to verify your setup.

Common Issues

Parser not found or fails to load

Symptoms:

• Error: Parser not available for language "xxx"
• Treesitter features not working for a specific language

Solutions:

1. Verify the parser is installed:

   local installed = require('nvim-treesitter.config').get_installed()
   print(vim.inspect(installed))
   

2. Check installation directory is in runtimepath:

   :checkhealth nvim-treesitter
   

   Look for the “Install directory for parsers and queries” section.

3. Manually check parser file exists:

   local config = require('nvim-treesitter.config')
   local parser_dir = config.get_install_dir('parser')
   local parser_file = parser_dir .. '/rust.so'
   print(vim.fn.filereadable(parser_file))
   

4. Reinstall the parser:

   :TSInstall! rust
   

   The ! forces reinstallation even if the parser exists.

Installation directory not writable

Symptoms:

• Error during :TSInstall: Could not create directory
• Health check reports: “is not writable”

Solutions:

1. Check directory permissions:

   local install_dir = require('nvim-treesitter.config').get_install_dir('')
   print("Directory: " .. install_dir)
   print("Writable: " .. tostring(vim.uv.fs_access(install_dir, 'w')))
   

2. Set a custom writable directory:

   require('nvim-treesitter').setup({
     install_dir = vim.fn.expand("~/.local/share/nvim-treesitter"),
   })
   

3. Fix permissions (Linux/macOS):

   chmod -R u+w ~/.local/share/nvim/site/
   

Tree-sitter CLI not found

Symptoms:

• Error during :TSInstall: tree-sitter-cli not found
• Health check shows “tree-sitter-cli not found”

Solutions:

1. Install tree-sitter CLI (minimum version 0.26.1):

   npm:

   npm install -g tree-sitter-cli
   

   cargo:

   cargo install tree-sitter-cli
   

   Homebrew (macOS):

   brew install tree-sitter
   

2. Verify installation:

   tree-sitter --version
   

3. Ensure it’s in PATH:

   print(vim.fn.exepath('tree-sitter'))
   

ABI version mismatch

Symptoms:

• Error: Parser ABI version mismatch
• Health check shows ABI version incompatibility
• Parser loads but crashes or behaves incorrectly

Solutions:

1. Check your Neovim’s ABI version:

   print("ABI version: " .. vim.treesitter.language_version)
   

   nvim-treesitter requires ABI >= 13 (lua/nvim-treesitter/health.lua:9)

2. Update Neovim to version 0.11 or later:

   # Check current version
   nvim --version
   

3. Regenerate parser from grammar if parser.c is outdated:

   :TSInstallFromGrammar rust
   

   This regenerates parser.c with the correct ABI version.

4. Update all parsers to match current ABI:

   :TSUpdate
   

Query file errors

Symptoms:

• Error: Invalid node type or Invalid field name
• Health check shows query errors for specific languages
• Syntax highlighting partially works or breaks

Solutions:

1. Check which query files have errors:

   :checkhealth nvim-treesitter
   

   Look for the “The following errors have been detected” section.

2. Identify problematic query files:

   local lang = 'rust'
   local query_type = 'highlights'
   local files = vim.treesitter.query.get_files(lang, query_type)
   for _, file in ipairs(files) do
     print(file)
   end
   

3. Update parser and queries together:

   :TSUpdate rust
   

4. Clear cached queries (if queries are modified):

   vim.treesitter.query.invalidate_cache()
   

5. Check for outdated custom queries if you have local overrides.

Curl or tar missing

Symptoms:

• Error during :TSInstall: curl not found or tar not found
• Installation fails to download or extract parsers

Solutions:

1. Install required tools:

   Linux (Debian/Ubuntu):

   sudo apt install curl tar
   

   Linux (Fedora/RHEL):

   sudo dnf install curl tar
   

   macOS:

   # Usually pre-installed, or use Homebrew:
   brew install curl
   

   Windows:

   • Install Git for Windows which includes curl and tar
   • Or use Windows Subsystem for Linux (WSL)

2. Verify tools are accessible:

   print(vim.fn.exepath('curl'))
   print(vim.fn.exepath('tar'))
   

Installation timeout

Symptoms:

• Parser installation hangs or times out
• Error: timeout after 60 seconds

Context: The installation timeout is set to 60000ms (60 seconds) per parser (lua/nvim-treesitter/install.lua:61).

Solutions:

1. Check network connectivity:

   curl -I https://github.com
   

2. Try installing parsers one at a time:

   :TSInstall rust
   :TSInstall lua
   

3. Use synchronous installation with longer timeout:

   require('nvim-treesitter').install('rust'):wait(300000) -- 5 minutes
   

4. Check if another installation is running: The installer prevents concurrent installations of the same language.

Dependency language missing

Symptoms:

• Query errors for a language that has dependencies
• Example: angular requires html and html_tags

Solution:

Dependencies are automatically installed by default. If you see this error:

1. Manually install dependencies:

   local parsers = require('nvim-treesitter.parsers')
   local deps = parsers['angular'].requires
   require('nvim-treesitter').install(deps)
   

2. Check dependency information:

   local parsers = require('nvim-treesitter.parsers')
   print(vim.inspect(parsers['angular']))
   

3. Verify all dependencies are installed:

   local installed = require('nvim-treesitter.config').get_installed()
   print(vim.inspect(installed))
   

Parsers not updating

Symptoms:

• :TSUpdate reports “All parsers are up-to-date” but issues persist
• Old parser behavior despite update command

Solutions:

1. Check if update is actually needed:

   local config = require('nvim-treesitter.config')
   local parsers = require('nvim-treesitter.parsers')
   
   local lang = 'rust'
   local current = config.get_installed_revision(lang)
   local latest = parsers[lang].install_info.revision
   
   print("Current: " .. (current or 'none'))
   print("Latest: " .. (latest or 'none'))
   

2. Force reinstall:

   :TSInstall! rust
   

3. Clear parser cache and reinstall:

   -- Remove parser file
   local config = require('nvim-treesitter.config')
   local parser_file = config.get_install_dir('parser') .. '/rust.so'
   vim.fn.delete(parser_file)
   
   -- Reinstall
   require('nvim-treesitter').install('rust')
   

Debugging Installation Issues

View Installation Logs

All installation operations are logged. View the logs with:

:TSLog

This shows detailed output from previous install, update, or uninstall operations, including:

• Download progress
• Compilation output
• Error messages
• File operations

Manual Installation Verification

To manually verify an installation:

local config = require('nvim-treesitter.config')
local lang = 'rust'

-- 1. Check parser file exists
local parser_dir = config.get_install_dir('parser')
local parser_file = parser_dir .. '/' .. lang .. '.so'
print("Parser exists: " .. tostring(vim.fn.filereadable(parser_file) == 1))

-- 2. Check queries directory exists
local query_dir = config.get_install_dir('queries') .. '/' .. lang
print("Queries exist: " .. tostring(vim.fn.isdirectory(query_dir) == 1))

-- 3. Try loading the parser
local ok, parser = pcall(vim.treesitter.language.add, lang)
print("Parser loads: " .. tostring(ok))

-- 4. Check query files
local query_groups = { 'highlights', 'locals', 'folds', 'indents', 'injections' }
for _, group in ipairs(query_groups) do
  local ok, err = pcall(vim.treesitter.query.get, lang, group)
  print(group .. ": " .. (ok and "OK" or "Error"))
end

Platform-Specific Issues

Windows

On Windows, parsers may be locked when in use. The installer uses a special renaming strategy to handle this (lua/nvim-treesitter/install.lua:302-304).

Common Windows issues:

1. Parser file is locked:

   • Restart Neovim before updating parsers
   • Close all buffers using the parser before updating

2. Path issues with spaces:

   • Ensure install_dir doesn’t contain spaces
   • Or use short path names (8.3 format)

3. Git Bash paths:

   • Ensure Git Bash is in PATH
   • Use forward slashes in install_dir configuration

macOS

Common macOS issues:

1. Xcode Command Line Tools required:

   xcode-select --install
   

2. Permission issues with Homebrew directories:

   # Fix Homebrew permissions
   sudo chown -R $(whoami) $(brew --prefix)/*
   

Linux

Common Linux issues:

1. Missing build tools:

   # Debian/Ubuntu
   sudo apt install build-essential
   
   # Fedora/RHEL
   sudo dnf groupinstall "Development Tools"
   

2. SELinux issues:

   # Check SELinux status
   sestatus
   
   # Temporarily disable if needed
   sudo setenforce 0
   

Getting Help

If you’ve tried the solutions above and still have issues:

1. Run the health check and save the output:

   :checkhealth nvim-treesitter > ~/nvim-treesitter-health.txt
   

2. Check the installation logs:

   :TSLog
   

3. Gather system information:

   print(vim.inspect(vim.uv.os_uname()))
   print("Neovim version: " .. tostring(vim.version()))
   print("ABI version: " .. vim.treesitter.language_version)
   

4. Report the issue at nvim-treesitter GitHub with:

   • Health check output
   • Installation logs
   • System information
   • Steps to reproduce

See Also

• Configuration - Custom installation directory setup
• Performance - Optimize installation performance
• Commands - Installation command reference