What causes "Failed to update plugin" in nocobase/nocobase?

Check the `cause` in the error stack for the root failure (npm vs DB) and fix that first

nocobase/nocobase · error · PluginCommandError

Failed to update plugin

Error message

Failed to update plugin

What it means

This error wraps any failure thrown by app.pm.update() during the 'yarn nocobase pm update' CLI command. The plugin manager's update routine reloads the plugin's package.json, re-downloads/reinstalls the package and refreshes plugin metadata; any failure in that pipeline (npm/network failure, package not found, DB write error) is caught and rethrown as a PluginCommandError with this message, with the root cause attached as `cause`.

Source

Thrown at packages/core/server/src/commands/pm.ts:83

      } catch (error) {
        throw new PluginCommandError(`Failed to add plugin`, { cause: error });
      }
    });

  pm.command('update')
    .argument('<packageNames...>')
    // .option('--path [path]')
    // .option('--url [url]')
    .option('--registry [registry]')
    .option('--auth-token [authToken]')
    .option('--version [version]')
    .action(async (packageNames, options) => {
      try {
        await app.pm.update(packageNames, {
          ...options,
        });
      } catch (error) {
        throw new PluginCommandError(`Failed to update plugin`, { cause: error });
      }
    });

  pm.command('enable-all')
    .ipc()
    .preload()
    .action(async () => {
      try {
        await app.pm.enable('*');
      } catch (error) {
        throw new PluginCommandError(`Failed to enable plugin`, { cause: error });
      }
    });

  pm.command('enable')
    .ipc()
    .preload()
    .arguments('<plugins...>')

View on GitHub (pinned to fa42722fef)

Solutions

Check the `cause` in the error stack for the root failure (npm vs DB) and fix that first
Verify the plugin package exists at the requested version: `npm view <package>@<version>` or check node_modules
Ensure NODE_MODULES_PATH is correct and node_modules is intact; reinstall with `yarn install`
Retry `yarn nocobase pm update <plugin>` after network/registry issues are resolved

Example fix

// before
yarn nocobase pm update @nocobase/plugin-users
// after (inspect root cause, pin a version that exists)
yarn nocobase pm update @nocobase/plugin-users@1.6.0

Defensive patterns

Strategy: try-catch

Validate before calling

const pkgPath = resolve(process.env.NODE_MODULES_PATH, pkgName, 'package.json');
if (!fs.existsSync(pkgPath)) throw new Error(`${pkgName} not installed before update`);

Try / catch

try {
  await app.pm.update([pkgName]);
} catch (error) {
  console.error('update failed:', error.cause ?? error);
  // inspect cause: npm vs DB failure
}

Prevention

Always log/read error.cause to get the root npm or DB error
Pin plugin versions compatible with your core version
Ensure registry access (set npm proxy/registry env) before updating
Keep node_modules intact; avoid manual pruning

When it happens

Trigger: Running `yarn nocobase pm update <plugins...>` when the target plugin package cannot be resolved in NODE_MODULES_PATH, the npm registry is unreachable or returns an error, version constraints conflict, or the underlying update transaction in the plugins repository fails.

Common situations: Updating a pro plugin whose new version is not yet published; offline or proxied npm environments; mismatched versions between @nocobase/core and the plugin; corrupted node_modules after a partial install.

Related errors

AI-assisted analysis of nocobase/nocobase@fa42722fef (2026-09-01). Data as JSON: /api/errors/716f5bb54f0471e7. Report an issue: GitHub.