paperclipai/paperclip · error

packageName is required and must be a string

Error message

packageName is required and must be a string

What it means

400 validation guard on POST /plugins/install. Fires when req.body.packageName is missing or not a string; the install endpoint requires a package name (npm package or local path) before any installation step runs.

Source

Thrown at server/src/routes/plugins.ts:1148

   * bundled plugin catalog root may be installed. npm/registry installs and
   * arbitrary local paths are rejected with `403`. Local paths are
   * canonicalized and validated on every instance.
   *
   * Response: `PluginRecord`
   *
   * Errors:
   * - `400` — validation failure or install error (package not found, bad manifest, etc.)
   * - `403` — install source not permitted on a cloud-managed instance
   * - `500` — installation succeeded but manifest is missing (indicates a loader bug)
   */
  router.post("/plugins/install", async (req, res) => {
    assertInstanceAdmin(req);
    assertPluginManagementVisible();
    const { packageName, version, isLocalPath } = req.body as PluginInstallRequest;

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

    if (version !== undefined && typeof version !== "string") {
      res.status(400).json({ error: "version must be a string if provided" });
      return;
    }

    if (isLocalPath !== undefined && typeof isLocalPath !== "boolean") {
      res.status(400).json({ error: "isLocalPath must be a boolean if provided" });
      return;
    }

    // Validate package name format
    const trimmedPackage = packageName.trim();
    if (trimmedPackage.length === 0) {
      res.status(400).json({ error: "packageName cannot be empty" });
      return;

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Include the required field(s) in the request path, query, or body as named by the error message, then retry.
2. Check the API contract in packages/shared validators for the exact required shape of this endpoint.

When it happens

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

Common situations: See trigger scenarios.

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