What to do when a language server doesn't start?

Make sure you have the latest version of lsp-zero

Everything here assumes you are using the v3.x branch of lsp-zero.

You can check the version of lsp-zero you have installed using this command.

:help lsp-zero-version

That command will take you to the help page of lsp-zero, and it should show you this.

Version                                                      lsp-zero-version

Current version: v3.x

The code on this version requires Neovim v0.8 or greater.

Ensure the executable is on your PATH

Before we start, do you know what is the "PATH"?

If the answer is "No, I don't know what the hell you are talking about?" I'm going to tell you.

The PATH is an environment variable that contains a list of folder locations
that the operating system searches for executable files.

Here are a couple of links that can be useful to you.

• How To View and Update the Linux PATH Environment Variable

• How to set the path and environment variables in Windows

Now that you know, we can move on.

You can check if Neovim can find the executable of a language server using this command.

:lua require('lsp-zero.check').executable('eslint')

Here eslint is just an example. You can replace it with the name of the language server you want to check.

If the command is successfull you should a message like this.

LSP server: eslint
+ "vscode-eslint-language-server" is executable

If the executable could not be found, update your PATH environment variable. Add the folder where the executable of the language server is located.

Inspect the log file

If the language server fails after it starts, look for an error message in the log file. Use this command.

:LspLog

Ensure mason-lspconfig knows about the server

If you are using mason-lspconfig to handle the automatic setup, the first thing you can do is make sure mason-lspconfig recognizes the server.

Execute this command to inspect the list of installed servers.

:lua = require('mason-lspconfig').get_installed_servers()

If everything is okay you should see a list like this.

{"tsserver", "eslint"}

If your language server is not on this list execute the command :LspInstall with the name of the server. For example:

:LspInstall eslint

Ensure the setup function for the language server was called

Open Neovim using this commmand nvim test. The idea here is that you open Neovim with an empty buffer with no filetype (why? just in case you are lazy loading lspconfig). Now execute the command :LspInfo, this will show a floating window with some information. You should have something like this.

 Press q or <Esc> to close this window. Press <Tab> to view server doc.
 
 Language client log: /home/dev/.local/state/nvim/lsp.log
 Detected filetype:  
 
 0 client(s) attached to this buffer: 
 
 Configured servers list: tsserver, eslint

Notice at the bottom it says Configured servers list, your language server should be there. If it isn't, you need to make sure lspconfig's setup function is being called.

If eslint were missing then you would need to make sure somewhere in your config this function is being called.

require('lspconfig').eslint.setup({})

If you used mason-lspconfig automatic setup then it's being called for you in the handlers option. You should have something like this.

require('mason-lspconfig').setup({
  handlers = {
    function(server_name)
      require('lspconfig')[server_name].setup({})
    end,
  }
})

Ensure root_dir can be detected

When you execute the command :LspInfo inside an existing file you should get more data about the server.

Sometimes you will get something like this.

 Other clients that match the filetype: typescript

 Config: eslint
 	filetypes:         javascript, typescript, vue, svelte, astro
 	root directory:    Not found.
 	cmd:               /home/dev/.local/bin/vscode-eslint-language-server --stdio
 	cmd is executable: true
 	autostart:         true

The important bit is this.

 	root directory:    Not found.

This means lspconfig could not figure out what is the root of your project.

lspconfig will look for some common configuration file in the current directory or the parent directories. If it can't find them the language server doesn't get attached to the file.

How do you know which files lspconfig looks for? Ideally, you would know because you read the documentation. Each server looks for a particular set of files and you can find that information here: server_configurations.md.

Sometimes the documentation in lspconfig just says see source file in the root_dir section. In this case what you can do is inspect the source code of lspconfig. You can use the command :LspZeroViewConfigSource with the name of a language server, this will open the configuration file for that server in a split window.

So you can inspect eslint config using this.

:LspZeroViewConfigSource eslint

Once there, you can look for a property called root_dir. This property is usually a lua function, so you might find some amount of logic there, but you can still get an idea of which files lspconfig looks for.