Vim Debugging Cookbook

by Noah Frederick | 2016/03/11

Recipes for resolving basic problems in Vim

Setting ‘foobar’ isn’t working.

Ensure that 'foobar' is indeed set in your buffer:

:verbose set foobar?

The output of the above command should clue you into what, if anything, is overriding your setting.

My x map isn’t working / Something unexpected happens when I press x.

Use the single-argument variant of the :map command to determine if and where a mapping was defined:

:verbose map x

To narrow down the list, use nmap for normal mode mappings, imap for insert mode, etc.

A common mistake that leads to unexpected behavior in a mapping is placing a comment on the same line, because the comment is interpreted as part of the mapping:

:nnoremap n nzz " This will blow up

Another common snag is the | (“bar”) character used to separate commands, allowing you to execute :next|update in one line, for example. A handful of commands allow a | in their arguments (e.g., :argdo), but most don’t.

:nnoremap <Leader>n :next|update<CR>

Is really equivalent to:

:nnoremap <Leader>n :next
:update<CR>

In addition to your mapping not working as expected, this can also cause unexpected behavior at startup. Use <Bar> in a mapping instead:

:nnoremap <Leader>n :next<Bar>update<CR>

My color scheme isn’t working / I’m seeing the wrong colors.

Make sure the color scheme supports terminal Vim (look for cterm* definitions in the script) or GUI Vim (look for gui*) depending on which you are using.

Make sure your TERM is accurate:

:echo $TERM

Vim depends on TERM to determine how many colors your terminal emulator can display.

I’m seeing an error message.

If the error message isn’t descriptive enough to tell what the problem is, you can often get more context by looking up the error code in Vim’s documentation:

:help E254

The foo.vim plug-in isn’t loading.

Are you sure? You can check the output of :scriptnames to see if it loaded and in what order it was sourced relative to other plug-ins.

Recipes for resolving basic problems in Vim

Further Reading