Cannot load plugin in status

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.

Solutions

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

Defensive patterns

Strategy: validation

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@3f1d897a7c (2026-08-18). Data as JSON: /api/errors/e647e17740ad05a4. Report an issue: GitHub.

Appendix: source

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

      return {
        total: pluginsToLoad.length,
        succeeded,
        failed,
        results: loadResults,
      };
    },

    // -----------------------------------------------------------------------
    // loadSingle
    // -----------------------------------------------------------------------

    /**
     * loadSingle — Loads and activates a single plugin by its ID.
     *
     * This method retrieves the plugin from the registry, ensures it's in a valid
     * state, and then calls activatePlugin to start its worker and register its
     * capabilities (tools, jobs, etc.).
     *
     * @param pluginId - The UUID of the plugin to load.
     * @param options - Optional activation behavior overrides.
     * @returns A promise that resolves with the result of the activation.
     */
    async loadSingle(pluginId: string, options: PluginLoadSingleOptions = {}): Promise<PluginLoadResult> {
      if (!runtimeServices) {
        throw new Error(
          "Cannot loadSingle: no PluginRuntimeServices provided. " +
            "Pass runtime services as the third argument to pluginLoader().",
        );
      }

      const plugin = (await registry.getById(pluginId)) as PluginRecord | null;
      if (!plugin) {
        throw new Error(`Plugin not found: ${pluginId}`);
      }

View on GitHub (pinned to 3f1d897a7c)