paperclipai/paperclip · error

Cannot reload built-in adapter.

Error message

Cannot reload built-in adapter.

What it means

Type guard on POST /api/adapters/:type/reload: the target is a builtin adapter type with no external override installed; builtins are compiled in and cannot be hot-reloaded, so the route returns 400 before busting the module cache.

Source

Thrown at server/src/routes/adapters.ts:601

    res.json({ type: adapterType, removed: true });
  });

  /**
   * POST /api/adapters/:type/reload
   *
   * Reload an external adapter at runtime (for dev iteration without server restart).
   * Busts the ESM module cache, re-imports the adapter, and re-registers it.
   *
   * Cannot be used on built-in adapter types.
   */
  router.post("/adapters/:type/reload", async (req, res) => {
    assertInstanceAdmin(req);
    assertAdapterManagementVisible();

    const type = req.params.type;

    // Built-in adapters cannot be reloaded unless overridden by an external one
    if (BUILTIN_ADAPTER_TYPES.has(type) && !getAdapterPluginByType(type)) {
      res.status(400).json({ error: "Cannot reload built-in adapter." });
      return;
    }

    // Reload the adapter module (busts ESM cache, re-imports)
    try {
      const newModule = await reloadExternalAdapter(type);

      // Not found in the external adapter store
      if (!newModule) {
        res.status(404).json({ error: `Adapter "${type}" is not an externally installed adapter.` });
        return;
      }

      // Swap in the reloaded module
      unregisterServerAdapter(type);
      registerWithSessionManagement(newModule);

View on GitHub (pinned to 5716fe907e)

Solutions

1. Built-in adapters cannot be reloaded; only reload externally installed adapters.

When it happens

Trigger: Thrown at server/src/routes/adapters.ts:544 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@5716fe907e (2026-08-18). Data as JSON: /api/errors/564685408481b41e. Report an issue: GitHub.