Fix "Extension is not compatible with the current version of VS Code" Error

What Happened

You tried to install or enable a VS Code extension and got this:

Extension '...' is not compatible with the current version of VS Code. Please update VS Code to use this extension.

The extension stayed disabled or refused to install. This usually comes down to one of three things:

Your VS Code is outdated and the extension needs a newer engine.
Your VS Code is recent but you installed an old extension version built for an older engine.
You're on VS Code Insiders (pre-release) and the extension hasn't caught up yet.

Why This Happens

Every extension declares a minimum engine version in its package.json:

"engines": {
  "vscode": "^1.85.0"
}

VS Code checks this at install time. If your version is older than what the extension requires, the install is blocked.

Sideloading an old .vsix is the flip side. Say you grabbed an extension built for VS Code 1.60 — it may call APIs that were removed by 1.85, triggering the same error in reverse.

Quick Fix: Update VS Code

This clears up about 90% of cases. Run the update from inside VS Code:

Windows / macOS

Open the Command Palette: Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).
Type Update: Check for Updates and press Enter.
VS Code downloads the update in the background. When the bottom-left button says Restart to Update, click it.

Linux (via terminal)

# Snap
sudo snap refresh code

# APT (official Microsoft repo)
sudo apt update && sudo apt install --only-upgrade code

# RPM/DNF
sudo dnf upgrade code

Verify the update worked

code --version

The first line is the version number — something like 1.91.0. Cross-check it against the extension's page on the Marketplace. The VS Code Engine field shows the minimum required version.

If You Can't Update VS Code

Locked-down corporate machines and CI environments often block updates entirely. The workaround: install an older extension version that matches what your VS Code can handle.

Option A — Install a specific version from the Marketplace UI

Open the Extensions panel (Ctrl+Shift+X).
Search for the extension and click its name to open the detail page.
Click the small arrow next to Install → Install Another Version…
Pick the latest version released before your VS Code version cutoff.

Option B — Download and sideload a .vsix

Go to the extension's page on marketplace.visualstudio.com.
Click Version History and download a compatible .vsix file.
Install it from the CLI:

code --install-extension path/to/extension-1.2.3.vsix

Or from the Extensions panel: click the … menu → Install from VSIX…

Edge Case: VS Code Insiders

Insiders builds carry a higher internal version number than the current stable release. Some extensions haven't declared compatibility with it yet. Your options:

Switch to the stable VS Code channel for that project.
Wait for the extension author to push an update — Insiders-breaking changes typically get patched within a week or two.
Enable pre-release extensions: on the extension detail page, toggle Switch to Pre-Release Version.

Permanent Fix: Keep VS Code Auto-Updated

A one-time settings change prevents this from happening again:

Open Settings: Ctrl+, (or Cmd+, on macOS).
Search for update mode.
Set Update: Mode to default — it downloads silently in the background, then prompts you to restart.

Or drop this directly in settings.json:

{
  "update.mode": "default"
}

Valid values: none, manual, start, default. Stick with default unless you have a specific reason to pin your version.

Verify the Fix

After updating VS Code or installing a compatible extension version:

Open the Extensions panel (Ctrl+Shift+X).
The extension should show as Enabled with no warning badge.
Check the Output panel (Ctrl+Shift+U, select Extension Host) for any remaining errors.
Run the extension's core feature — if it works, you're done.

Still showing as incompatible? Open Developer Tools via Help → Toggle Developer Tools. The Console tab will name the exact API call that failed — far more useful than the surface-level error message.

Summary

Most of the time: update VS Code (code --version shows what you have).
Can't update: install an older extension version via Install Another Version… or a downloaded .vsix.
On Insiders: try the pre-release extension channel or switch to stable.
Long-term: set update.mode to default in settings.