Troubleshooting

For architectural limitations (visual block mode, macros, registers), see KNOWN_ISSUES.md.

Installation Issues

Configuration Not Loading

Symptoms:

Keybindings don't work after copying files
VS Code looks the same as before

Solutions:

Verify file location:

# macOS
ls -la ~/Library/Application\ Support/Code/User/settings.json
ls -la ~/Library/Application\ Support/Code/User/keybindings.json

# Linux
ls -la ~/.config/Code/User/settings.json
ls -la ~/.config/Code/User/keybindings.json

# Windows (PowerShell)
dir $env:APPDATA\Code\User\settings.json
dir $env:APPDATA\Code\User\keybindings.json

Check file permissions:

chmod 644 ~/Library/Application\ Support/Code/User/settings.json
chmod 644 ~/Library/Application\ Support/Code/User/keybindings.json

Restart VS Code completely — close all windows, quit (not just close), reopen, and test with <leader>ff.
Verify JSON syntax — open settings.json in VS Code and check for red squiggly lines.

Vim Extension Not Installing

Symptoms:

code --install-extension vscodevim.vim fails
Extension not appearing in Extensions panel

Solutions:

Install manually: Ctrl+Shift+X → search "Vim" → install "Vim" by vscodevim.

Test marketplace connectivity:

curl -I https://marketplace.visualstudio.com

Clear extension cache:
```
# macOS/Linux
rm -rf ~/.vscode/extensions
```
Then reinstall extensions.

Leader Key Problems

Space Moves Cursor Instead of Triggering Leader

Symptoms:

Pressing space in Normal mode moves cursor right
Leader keybindings don't work

Diagnosis: Open settings.json and verify "vim.leader": "<space>" is present.

Solutions:

Ensure leader is configured:
```
{
  "vim.leader": "<space>"
}
```
Verify you're in Normal mode — status bar should be blue (not green for Insert). Press Esc first, then space.
Check for conflicting settings: search settings.json for duplicate "leader" mentions.
Restart VS Code.

Leader Keybindings in Wrong File

Symptoms:

Leader bindings not working
Other keybindings work fine

Cause: Leader bindings placed in keybindings.json instead of settings.json.

Solution: Leader bindings must be in settings.json under vim.normalModeKeyBindingsNonRecursive. Move them if they're in keybindings.json.

// settings.json — correct location
{
  "vim.normalModeKeyBindingsNonRecursive": [
    {
      "before": ["<leader>", "f", "f"],
      "commands": ["workbench.action.quickOpen"]
    }
  ]
}

Performance Issues

Typing Lag in Insert Mode

Symptoms:

Characters appear slowly when typing
Delay between keypress and character appearing
Cursor movement feels sluggish

Solutions:

Add dedicated thread setting:

{
  "extensions.experimental.affinity": {
    "vscodevim.vim": 1
  }
}

On macOS, enable key repeat:

defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false

Then restart your Mac (not just VS Code).

Disable unused extensions — open Extensions panel (Ctrl+Shift+X) and disable extensions you don't use.

Reduce editor animations:

{
  "editor.smoothScrolling": false,
  "workbench.editor.enablePreview": false,
  "editor.cursorSmoothCaretAnimation": "off"
}

Keybinding Conflicts

Ctrl+h Deletes Instead of Navigating

Symptoms:

Ctrl+h deletes character (like backspace)
Doesn't navigate to left split

Cause: macOS Terminal maps Ctrl+h to delete. The keybinding in keybindings.json may also need a !terminalFocus guard.

Solution: Add to keybindings.json:

{
  "key": "ctrl+h",
  "command": "workbench.action.navigateLeft",
  "when": "vim.active && vim.mode != 'Insert'"
},
{
  "key": "ctrl+h",
  "command": "-workbench.action.terminal.sendSequence"
}

Bracket Navigation Not Working

Symptoms:

[d, ]d, [h, ]h don't work
oem_4 and oem_6 not recognized

Cause: Non-US keyboard layout.

Solution: In keybindings.json, replace:

// OLD (US layout)
"key": "oem_4"  // [
"key": "oem_6"  // ]

// NEW (international)
"key": "[BracketLeft]"
"key": "[BracketRight]"

Suggestion Widget Conflicts

Symptoms:

Ctrl+j/k doesn't navigate suggestions
Autocomplete breaks

Solution: Ensure these are in keybindings.json:

{
  "key": "ctrl+j",
  "command": "selectNextSuggestion",
  "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus"
},
{
  "key": "ctrl+k",
  "command": "selectPrevSuggestion",
  "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus"
}

Terminal Keybindings Conflict

Symptoms:

Ctrl+h/j/k/l doesn't work when terminal is focused

Solution: Add terminal-specific when clauses:

{
  "key": "ctrl+h",
  "command": "workbench.action.navigateLeft",
  "when": "vim.active && !terminalFocus"
}

Platform-Specific Issues

macOS: Key Repeat Not Working

Symptoms:

Holding j or k shows accent menu
Can't hold keys to repeat

Solution:

defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false
defaults write com.cursor.Cursor ApplePressAndHoldEnabled -bool false
defaults write com.google.antigravity ApplePressAndHoldEnabled -bool false

Restart your Mac after running these commands. Verify with: defaults read com.microsoft.VSCode ApplePressAndHoldEnabled — should output 0.

Windows: PowerShell Commands Don't Work

Symptoms:

Copy-Item command not found

Solutions:

Use PowerShell, not Command Prompt.

Alternative using cmd.exe:

copy config\settings.json %APPDATA%\Code\User\
copy config\keybindings.json %APPDATA%\Code\User\

Linux: Clipboard Not Working

Symptoms:

y (yank) doesn't copy to clipboard

Solution:

Install clipboard utility:

sudo apt install xclip      # Debian/Ubuntu
sudo dnf install xclip      # Fedora
sudo pacman -S xclip        # Arch

Enable system clipboard:
```
{ "vim.useSystemClipboard": true }
```

Extension Issues

GitLens Keybindings Not Working

Symptoms:

<leader>gb (blame) doesn't work
<leader>gl (log) doesn't work

Diagnosis:

code --list-extensions | grep gitlens
# Should show: eamodio.gitlens

Solutions:

Install GitLens:

code --install-extension eamodio.gitlens

Verify you're in a git repository (git status).
Check GitLens is enabled in the Extensions panel.
Reload window: Ctrl+Shift+P → "Developer: Reload Window".

Settings Cycler Not Working

Symptoms:

<leader>ul (line numbers toggle) doesn't work

Solutions:

Install Settings Cycler:

code --install-extension hoovercj.vscode-settings-cycler

Uncomment settings.cycle section in settings.json:

"settings.cycle": [
  {
    "id": "lineNumbers",
    "values": [
      { "editor.lineNumbers": "on" },
      { "editor.lineNumbers": "relative" },
      { "editor.lineNumbers": "off" }
    ]
  }
]

Which Key Not Appearing

Symptoms:

No keybinding menu appears after pressing <Tab>

Note: VimCode works without Which Key — it's optional. All <leader>* bindings function without it. The which-key trigger is <Tab> (not <space>).

To install:

code --install-extension VSpaceCode.whichkey

After installing: press <Tab> in Normal mode (not <space>) — the menu should appear.

Why not <space>? <space> is also vim.leader, and the leader intercepts the keypress before which-key can fire. <Tab> avoids this conflict. See KNOWN_ISSUES.md for details.

Git Integration Problems

Git Commands Don't Work

Symptoms:

<leader>gg does nothing
Source Control is empty

Diagnosis:

git status    # Check if folder is a git repo
git --version # Check git is installed

Solutions:

Initialize git repository: git init
Open the folder containing .git — File → Open Folder → navigate to git repository root.

Install git if missing:

brew install git     # macOS
sudo apt install git # Linux

If GitLens blame shows "Not a Git Repository": ensure you've opened the repository root, not a parent directory. Verify: ls -la .git

Hunk Navigation Shows No Changes

Symptoms:

[h and ]h do nothing

Causes: No uncommitted changes, file not in git repo, or file is new (not tracked).

Solutions:

Make changes to a tracked file.
Leave some changes unstaged.
Try [h and ]h again.

Editor Behavior Issues

Line Numbers Not Relative

Symptoms:

Line numbers show absolute, not relative

Solution:

{
  "editor.lineNumbers": "relative",
  "vim.smartRelativeLine": true
}

Line numbers are relative in Normal/Visual modes and absolute in Insert mode.

Status Bar Color Not Changing

Symptoms:

Status bar stays same color in all modes

Solution:

{
  "vim.statusBarColorControl": true,
  "vim.statusBarColors.normal": "#519aba",
  "vim.statusBarColors.insert": "#98c379",
  "vim.statusBarColors.visual": "#c678dd",
  "vim.statusBarColors.replace": "#e06c75"
}

Visual Block Mode Not Working

Symptoms:

Ctrl+v doesn't enter visual block mode

Cause: Ctrl+v is paste in VS Code by default. Visual block paste is also unreliable in VSCodeVim. See KNOWN_ISSUES.md.

Solution: Use VS Code's column edit instead:

Alt+Click for multiple cursors
Alt+Shift+Drag for column selection

Search Highlighting Persists

Symptoms:

Search highlights stay after search

Solution:

<leader>ur      # Clear search highlight
:noh            # Vim native alternative

Still having issues? Open a GitHub Issue with your VS Code version, OS, steps to reproduce, expected vs actual behavior, and relevant settings.json sections.

See also: SETUP.md — installation guide | KEYBINDINGS.md — keybinding reference | KNOWN_ISSUES.md — architectural limitations

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting

Installation Issues

Configuration Not Loading

Vim Extension Not Installing

Leader Key Problems

Space Moves Cursor Instead of Triggering Leader

Leader Keybindings in Wrong File

Performance Issues

Typing Lag in Insert Mode

Keybinding Conflicts

Ctrl+h Deletes Instead of Navigating

Bracket Navigation Not Working

Suggestion Widget Conflicts

Terminal Keybindings Conflict

Platform-Specific Issues

macOS: Key Repeat Not Working

Windows: PowerShell Commands Don't Work

Linux: Clipboard Not Working

Extension Issues

GitLens Keybindings Not Working

Settings Cycler Not Working

Which Key Not Appearing

Git Integration Problems

Git Commands Don't Work

Hunk Navigation Shows No Changes

Editor Behavior Issues

Line Numbers Not Relative

Status Bar Color Not Changing

Visual Block Mode Not Working

Search Highlighting Persists