paperclipai/paperclip · error

Cannot load plugin in status '${plugin.status}'. Plugin must

Error message

Cannot load plugin in status '${plugin.status}'. Plugin must be in 'installed' or 'ready' status.

What it means

State-machine guard in loadSingle: the plugin's status is neither installed nor ready, so it cannot be loaded (e.g. it is disabled, errored, or uninstalled). Callers must move the plugin into a loadable state first; the plugin's lifecycle status is at fault.

Source

Thrown at server/src/services/plugin-loader.ts:2038

      // If the plugin is in 'installed' status, transition it to 'ready' first.
      // lifecycleManager.load() transitions the status AND activates the plugin
      // via activateReadyPlugin() → loadSingle() (recursive call with 'ready'
      // status) → activatePlugin(). We must NOT call activatePlugin() again here,
      // as that would double-start the worker and duplicate registrations.
      if (plugin.status === "installed") {
        await runtimeServices.lifecycleManager.load(pluginId);
        const updated = (await registry.getById(pluginId)) as PluginRecord | null;
        if (!updated) throw new Error(`Plugin not found after status update: ${pluginId}`);
        return {
          plugin: updated,
          success: true,
          registered: { worker: true, eventSubscriptions: 0, jobs: 0, webhooks: 0, tools: 0 },
        };
      }

      if (plugin.status !== "ready") {
        throw new Error(
          `Cannot load plugin in status '${plugin.status}'. ` +
            `Plugin must be in 'installed' or 'ready' status.`,
        );
      }

      return activatePlugin(plugin, {
        markErrorOnFailure: options.markErrorOnFailure ?? true,
      });
    },

    // -----------------------------------------------------------------------
    // unloadSingle
    // -----------------------------------------------------------------------

    async unloadSingle(pluginId: string, pluginKey: string): Promise<void> {
      if (!runtimeServices) {
        throw new Error(
          "Cannot unloadSingle: no PluginRuntimeServices provided.",

View on GitHub (pinned to 120ae5428f)

Solutions

1. Transition the plugin to 'installed' or 'ready' status before loading (complete install/build steps first).

When it happens

Trigger: Thrown at server/src/services/plugin-loader.ts:2038 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/e647e17740ad05a4. Report an issue: GitHub.