paperclipai/paperclip · error

packageName is required and must be a string.

Error message

packageName is required and must be a string.

What it means

Body-shape guard on POST /api/adapters/install: the request body lacks a usable packageName (missing, empty, or non-string), so the install cannot determine which npm package or local path to install and the route returns 400 before any install attempt.

Source

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

  });

  /**
   * POST /api/adapters/install
   *
   * Install an external adapter from an npm package or local path.
   *
   * Request body:
   * - packageName: string (required) — npm package name or local path
   * - isLocalPath?: boolean (default false)
   * - version?: string — target version for npm packages
   */
  router.post("/adapters/install", async (req, res) => {
    assertInstanceAdmin(req);
    assertAdapterCodeInstallAllowed();
    assertAdapterManagementVisible();

    const { packageName, isLocalPath = false, version } = req.body as AdapterInstallRequest;

    if (!packageName || typeof packageName !== "string") {
      res.status(400).json({ error: "packageName is required and must be a string." });
      return;
    }

    // Strip version suffix if the UI sends "pkg@1.2.3" instead of separating it
    // e.g. "@henkey/hermes-paperclip-adapter@0.3.0" → packageName + version
    let canonicalName = packageName;
    let explicitVersion = version;
    const versionSuffix = packageName.match(/@(\d+\.\d+\.\d+.*)$/);
    if (versionSuffix) {
      // For scoped packages: "@scope/name@1.2.3" → "@scope/name" + "1.2.3"
      // For unscoped: "name@1.2.3" → "name" + "1.2.3"
      const lastAtIndex = packageName.lastIndexOf("@");
      if (lastAtIndex > 0 && !explicitVersion) {
        canonicalName = packageName.slice(0, lastAtIndex);
        explicitVersion = versionSuffix[1];
      }

View on GitHub (pinned to 5716fe907e)

Solutions

1. Provide packageName as a string in the request body.

When it happens

Trigger: Thrown at server/src/routes/adapters.ts:258 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/45cb7f34480b75aa. Report an issue: GitHub.