neoclide/coc.nvim · error · Error

Unable to load extension at ${filepath}

Error message

Unable to load extension at ${filepath}

What it means

Thrown by ExtensionManager.load() when none of the loading paths (directory, single file, sourceCode) yields an extension name, so nothing was registered at the given filepath. Typically the path is neither a directory with a valid package.json nor a loadable extension file.

Source

Thrown at src/extension/manager.ts:665

   * load extension in folder or file
   */
  public async load(filepath: string, active: boolean, options?: ExtensionLoadOptions): Promise<ExportExtension> {
    let name: string
    if (options?.sourceCode) {
      let extensionRoot = options.extensionRoot ?? filepath
      let obj = loadJson(path.join(extensionRoot, 'package.json')) as any
      name = obj.name
      if (!name) throw new Error(`Unable to load extension at ${extensionRoot}, missing package.json`)
      await this.unloadExtension(name)
      await this.registerExtension(extensionRoot, obj, ExtensionType.Local, true, options)
    } else if (isDirectory(filepath)) {
      let obj = loadJson(path.join(filepath, 'package.json')) as any
      name = obj.name
      await this.loadExtension(filepath, true)
    } else {
      name = await this.loadExtensionFile(filepath, true)
    }
    if (!name) throw new Error(`Unable to load extension at ${filepath}`)
    let disabled = this.states.isDisabled(name)
    if (disabled) throw new Error(`extension ${name} is disabled`)
    let item = this.getExtension(name)
    if (active) await this.activate(name)
    return {
      get isActive() {
        return item.extension.isActive
      },
      get name() {
        return name
      },
      get api() {
        return item.extension.exports
      },
      get exports() {
        let module = item.extension.module ?? {}
        return omit(module, ['activate'])
      },

View on GitHub (pinned to 50e974d969)

Solutions

  1. Verify the filepath exists (`ls <filepath>`)
  2. If loading a directory, ensure it has a valid package.json with `name`
  3. If loading a single file, ensure a valid package.json exists in its directory
  4. Reinstall/rebuild the extension

Example fix

// before
await coc.extensions.load('~/myext/dist/bundle.js', true)
// after
await coc.extensions.load('~/myext', true) // valid extension root with package.json
Defensive patterns

Strategy: try-catch

Validate before calling

const fs = require('fs');
if (!fs.existsSync(filepath)) throw new Error(`path missing: ${filepath}`);
if (fs.statSync(filepath).isDirectory() && !fs.existsSync(require('path').join(filepath, 'package.json'))) throw new Error('dir lacks package.json');

Try / catch

try {
  await coc.extensions.load(filepath, true);
} catch (e) {
  if (String(e.message).startsWith('Unable to load extension at')) {
    console.error(`Cannot load extension from ${filepath}; check path and package.json`);
  } else throw e;
}

Prevention

When it happens

Trigger: coc.extensions.load(filepath, active) where filepath is not a directory and loadExtensionFile() returns no name (missing/invalid package.json inside the file's folder, wrong path, non-existent file).

Common situations: Typo in extension path; passing a compiled .js file whose sibling package.json is missing; loading from a removed/uninstalled extension directory.

Related errors

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