Neovim troubleshooting

When troubleshooting the GitLab plugin for Neovim, you should confirm if an issue still occurs in isolation from other Neovim plugins and settings. First, run the Neovim testing steps, then the GitLab Duo Code Suggestions troubleshooting steps.

If the steps on this page don’t solve your problem, check the list of open issues in the Neovim plugin’s project. If an issue matches your problem, update the issue. If no issues match your problem, create a new issue.

For troubleshooting the extension for GitLab Duo Code Suggestions, see Troubleshooting Code Suggestions.

Test your Neovim configuration

The maintainers of the Neovim plugin often ask for the results of these checks as part of troubleshooting:

  1. Ensure you have generated help tags.
  2. Run :checkhealth.
  3. Enable debug logs.
  4. Try to reproduce the problem in a minimal project.

Generate help tags

If you see the error E149: Sorry, no help for gitlab.txt, you need to generate help tags in Neovim. To resolve this issue:

  • Run either of these commands:
    • :helptags ALL
    • :helptags doc/ from the root directory of the plugin.

Run :checkhealth

Run :checkhealth gitlab* to get diagnostics on your current session configuration. These checks help you identify and resolve configuration issues on your own.

Enable debug logs

To enable more logging:

  • Set the vim.lsp log level in init.lua: 

    vim.lsp.set_log_level('debug')

Reproduce the problem in a minimal project

To help improve the maintainers’ ability to understand and resolve your issue, create a sample configuration or project that reproduces your issue. For example, when troubleshooting a problem with Code Suggestions:

  1. Create a sample project: 

    mkdir issue-25
cd issue-25
echo -e "def hello(name)\n\nend" > hello.rb

  2. Create a new file named minimal.lua, with these contents: 

    vim.lsp.set_log_level('debug')

vim.opt.rtp:append('$HOME/.local/share/nvim/site/pack/gitlab/start/gitlab.vim')

vim.cmd('runtime plugin/gitlab.lua')

-- gitlab.config options overrides:
local minimal_user_options = {}
require('gitlab').setup(minimal_user_options)

  3. In a minimal Neovim session, edit hello.rb: 

    nvim --clean -u minimal.lua hello.rb
  4. Attempt to reproduce the behavior you experienced. Adjust minimal.lua or other project files as needed.

  5. View recent entries in ~/.local/state/nvim/lsp.log and capture relevant output: 

    echo ~/.local/state/nvim/lsp.log

Error: GCS:unavailable

This error happens when your local project has not set a remote in .git/config.

To resolve this issue: add a Git remote in your local project using git remote add.