Troubleshooting Steps for When a Vim Plugin Is Not Working
Most of the time things go smoothly but what happens if you add a plugin to your config and it doesn't work?
Prefer watching video? Here’s it is on YouTube.
This post will cover steps you can take no matter which plugin manager you’re using but it will also include specific steps for Vim Plug because that happens to be a really popular plugin manager that I use. We’ll also cover tactics that work with both Vim and Neovim.
# Is the Plugin Loaded?
I would start here. If you’re using Vim Plug you can run :PlugStatus and expect
to see the name of the plugin you want installed along with an OK.
That output looks something like this:
Finished. 0 error(s).
[===========================================================]
- fzf: OK
- vim-git: OK
- markdown-preview.nvim: OK
- vim-snippets: OK
...
If you don’t see your plugin listed, chances are you forgot to run
:PlugInstall after you added the plugin to your .vimrc file, or maybe your
vim config didn’t get saved.
If you’re not using Vim Plug you can run :scriptnames and look for the plugin
in that output. It’s a bit harder to read but you should see the plugin listed.
# Enable Verbose Logging
This could be helpful if a plugin is being loaded but it’s not working for a specific reason. Sometimes it’s not easy to know why it’s not working based on seeing a 1 line error output in the status bar.
For that you can launch Vim in verbose mode and tell it to write out a log
file. You can run vim -Vmylog . where mylog is whatever file name you want
the log to be.
Depending on how big your Vim config is, there will be a lot of output here but
you’ll be able to see exactly what’s being loaded and what’s throwing errors.
You might want to search this file for Error or the name of the plugin.
From there you can either dive into the plugin and try to fix it or open an issue and hope the plugin author or community can help figure out what went wrong.
# Go as Vanilla as Possible
Reducing variables is a very useful debugging tactic in general. In this case you’ll want to disable all plugins except the one not working and potentially eliminate as much of your custom configuration as possible.
With Vim Plug you can comment out all of your plugins except the one you’re testing and then reload Vim. This strategy should work with most plugin managers.
Additionally, if needed you can start commenting out some of your custom configuration until you find a root cause. You can do chunks at a time, consider it an exercise in performing a bisection search.
Technically Vim and Neovim both have a --clean flag you can run such as vim --clean . but that will avoid loading all plugins and configuration which will
be overkill for this use case since we do need to load 1 specific plugin and
maybe its configuration.
# Vim vs Neovim
We all have our preferences here. If a plugin isn’t working with your preferred editor it could be worth checking to see if it works with the other one.
This is especially true for non-Neovim specific plugins. If you use Neovim it’s worth checking to see if it works with Vim.
The goal here isn’t to switch to the other editor permanently. It’s to reduce variables because maybe you can isolate why it’s working in Vim but not Neovim or vice versa.
The video below covers running through all of the above debugging steps.
# Demo Video
Timestamps
- 0:39 – Checking if a plugin is loaded
- 2:21 – Instructing Vim to write verbose logs
- 4:48 – Disabling most plugins and configuration
- 6:45 – Try temporarily switching between Vim and Neovim
- 7:52 – Shout-out to a viewer who prompted me to make this video
What’s your best tips for debugging Vim plugins? Let me know below.