neoclide/coc.nvim · error · Error

coc.nvim version not match, required ${engines['coc']}

Error message

coc.nvim version not match, required ${engines['coc']}

What it means

Thrown by loadGlobalJsonAsync when package.json declares engines.coc but the running coc.nvim version does not satisfy that range. The extension explicitly requires a different coc.nvim version.

Source

Thrown at src/extension/stat.ts:282

  return res != null && errors.length == 0
}

function getEntryFile(main: string | undefined): string {
  if (!main) return 'index.js'
  if (!main.endsWith('.js')) return main + '.js'
  return main
}

export async function loadGlobalJsonAsync(folder: string, version: string): Promise<ExtensionJson> {
  let jsonFile = path.join(folder, 'package.json')
  let content = await readFile(jsonFile, 'utf8')
  let packageJSON = JSON.parse(content) as ExtensionJson
  let { engines } = packageJSON
  let main = getEntryFile(packageJSON.main)
  if (!engines || (typeof engines.coc !== 'string' && typeof engines.vscode !== 'string')) throw new Error('Invalid engines field')
  let keys = Object.keys(engines)
  if (keys.includes('coc') && !semver.satisfies(version, engines['coc'].replace(/^\^/, '>='))) {
    throw new Error(`coc.nvim version not match, required ${engines['coc']}`)
  }
  if (!engines.vscode && !fs.existsSync(path.join(folder, main))) {
    throw new Error(`main file ${main} not found, you may need to build the project.`)
  }
  return packageJSON
}

export function loadExtensionJson(folder: string, version: string, errors: string[]): ExtensionJson | undefined {
  let jsonFile = path.join(folder, 'package.json')
  if (!fs.existsSync(jsonFile)) {
    errors.push(`package.json not found in ${folder}`)
    return undefined
  }
  let packageJSON = loadJson(jsonFile) as ExtensionJson
  let { name, engines } = packageJSON
  let main = getEntryFile(packageJSON.main)
  if (!name) errors.push(`can't find name in package.json`)
  if (!engines || !objectLiteral(engines)) {

View on GitHub (pinned to 50e974d969)

Solutions

  1. Update coc.nvim to a version satisfying the required range (see the message)
  2. Install an older extension release compatible with your coc.nvim
  3. Fix/relax the engines.coc range if you maintain the extension

Example fix

// before (package.json)
"engines": { "coc": ">=1.1.0" }
// after (if staying on older coc)
"engines": { "coc": ">=0.0.80" }
Defensive patterns

Strategy: try-catch

Validate before calling

const semver = require('semver');
const required = pkg.engines?.coc?.replace(/^\^/, '>=');
if (required && !semver.satisfies(cocVersion, required)) console.warn('update coc.nvim before loading');

Try / catch

try {
  await coc.extensions.load(folder, true);
} catch (e) {
  if (String(e.message).includes('coc.nvim version not match')) {
    console.error('Run :CocUpdate or update coc.nvim to satisfy the extension requirement');
  } else throw e;
}

Prevention

When it happens

Trigger: Loading an extension whose engines.coc range (with ^ treated as >=) is not satisfied by the current coc.nvim semver, e.g. extension requires >=1.0.0 while installed coc is 0.0.82.

Common situations: Outdated coc.nvim after installing a new extension; extension built for a newer coc API; running a development coc build with an older version string.

Related errors

AI-assisted analysis of neoclide/coc.nvim@50e974d969 (2026-08-31). Data as JSON: /api/errors/fc008dd30bcf06b7. Report an issue: GitHub.