Troubleshooting Center

The editor or Node.js executable seen by Vim may be older than the current requirements: Vim 9.0.0438+, Neovim 0.8.0+, and Node.js 22.15.0+.

1. 1Upgrade Vim, Neovim, or Node.js when the reported version is below the documented requirement.
2. 2If the shell has a newer Node.js, make sure Vim inherits that PATH or set `g:coc_node_path` to the intended executable.
3. 3Restart the editor, run `:CocInfo`, and inspect `:messages` if initialization still fails.

A competing insert-mode mapping, an incompatible completeopt value, or no completion provider is active for the current filetype.

1. 1Use `set completeopt=noinsert,noselect,menuone` while testing completion.
2. 2Run :set filetype? in the affected buffer. An empty or incorrect filetype means the language extension may not activate; fix file detection before changing completion mappings.
3. 3Run :CocList extensions to check installation and activation, then :CocList sources in the affected buffer. If the language source is missing, follow the language-server startup guide below.
4. 4If a source is available, type a member access such as user. in the TypeScript walkthrough. If suggestions appear but Tab or Enter does not accept them, inspect those mappings instead of reinstalling the server.
5. 5Remove or adjust competing <Tab>/<CR> mappings, then restart coc.nvim with `:CocRestart`.

coc.nvim does not bundle language servers. The extension or `languageserver` entry may be missing, its executable may not be on PATH, or the workspace root may not match the project.

1. 1Install the language extension, or configure `languageserver` in `coc-settings.json`; do not configure the same server twice.
2. 2If the extension is absent from :CocList extensions, finish its installation first. If installed, open a saved file with its supported filetype and inspect :CocList services again.
3. 3For a manually configured executable, verify that command in the environment that launches Vim/Neovim. Extensions can bundle their server; a missing global pyright command alone does not prove coc-pyright is broken.
4. 4If a service is stopped or fails to initialize, inspect its output channel and :CocOpenLog. Resolve the first concrete error, such as an executable not found or invalid server argument, before restarting.
5. 5Check `rootPatterns` and open a file inside the intended project root before running `:CocRestart`.

The active provider has not initialized, the current buffer is outside its workspace, or the server does not advertise the requested capability.

1. 1Wait for the server to finish initialization and inspect its output channel for errors.
2. 2Confirm that the filetype and workspace root match the language extension configuration.
3. 3Check the mapping with `:verbose nmap gd`; use the documented `<Plug>(coc-definition)` mapping when appropriate.

The npm registry, proxy, certificate, or npm executable used by coc.nvim is unavailable in the current environment.

1. 1Confirm that the npm executable is available and that the configured registry can be reached outside Vim.
2. 2For a proxy, configure `http.proxy` or let coc.nvim inherit `http_proxy`/`https_proxy`; use `http.proxyCA` for a required CA.
3. 3If your organization uses a private registry, set `coc.nvim:registry` in `~/.npmrc`, then retry `:CocInstall`.

The useful detail is in the coc.nvim log or the stderr stream of its Node.js process, not in the notification alone.

1. 1Use `:CocOpenLog` to inspect the log; it is cleared when coc.nvim starts, so reproduce the issue after opening Vim.
2. 2Use `:CocPrintErrors` for stderr from the Node.js process and `:CocCommand workspace.showOutput` for extension or server channels.
3. 3For a short diagnostic session, set `NVIM_COC_LOG_LEVEL=debug` before launching Vim/Neovim, then remove it when finished.

Vim/Neovim may inherit a different PATH, Node executable, npm configuration, or coc data/config home than the terminal used to install the extension.

1. 1Start Vim/Neovim from an environment where the intended Node.js executable is on PATH, or set `g:coc_node_path` to an explicit executable path.
2. 2Check the extension output channel for the npm command and path that were actually used.
3. 3Remember that Windows uses `~/AppData/Local/nvim` and `~/AppData/Local/coc` for the relevant default homes documented by coc.nvim.

coc.nvim starts its Node process and configured language-server commands in the environment where Vim/Neovim is running; a local PATH or project root may not exist on the remote host.

1. 1Install Node.js, the coc extension, and the language-server executable in the environment that runs Vim/Neovim.
2. 2Use a remote project path in `rootPatterns` and ensure the remote filesystem is accessible to the server process.
3. 3Copy the remote output channel and `:CocInfo` results when reporting the problem; redact usernames, tokens, and private paths.

File watching, diagnostics, or a language server is processing generated or dependency folders that do not need to be part of the workspace.

1. 1Use `workspace.ignoredFolders` and `fileSystemWatch.ignoredFolders` for generated or dependency paths such as `node_modules`, `dist`, or `target`.
2. 2Inspect the file watcher output (native and Watchman backends) with `:CocCommand workspace.showOutput watchman` when file watching is involved.
3. 3Re-enable coc.nvim with `:CocEnable`, then narrow the responsible extension or language server using `:CocList services`.

Another plugin, runtimepath entry, mapping, or user/workspace setting changes the behavior before coc.nvim handles the event.

1. 1Start with only coc.nvim, the required extension or language-server setting, and the relevant mapping; add other plugins back one at a time.
2. 2Use `:verbose imap <Tab>` or `:verbose nmap gd` to find the file that last defined a conflicting mapping.
3. 3Check both user and workspace settings, then run `:CocRestart` after changing configuration.