paperclipai/paperclip · error

Invalid localPath: ${validated.reason}

Error message

Invalid localPath: ${validated.reason}

What it means

canonicalizeLocalPluginPath rejected the local install path with the reason in validated.reason (traversal segments, symlink aliasing, or non-existent path); local installs must canonicalize to a valid path.

Source

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

    // Cloud install floor: on harness-managed instances only bundled-catalog
    // sources are installable, regardless of actor privileges or flag state.
    const cloudManaged = isCloudManagedInstance();
    if (cloudManaged && !isLocalPath) {
      res.status(403).json({
        error:
          "npm installs are disabled on cloud-managed instances; only plugins bundled with the application may be installed",
      });
      return;
    }

    // Canonicalize local install paths on every instance so traversal
    // segments and symlinks cannot smuggle an aliased path past validation.
    let canonicalLocalPath: string | undefined;
    if (isLocalPath) {
      const validated = await canonicalizeLocalPluginPath(trimmedPackage);
      if (!validated.ok) {
        res.status(400).json({ error: `Invalid localPath: ${validated.reason}` });
        return;
      }
      if (cloudManaged && !(await isWithinBundledPluginRoot(validated.canonicalPath))) {
        res.status(403).json({
          error:
            "cloud-managed instances may only install plugins from the bundled plugin catalog",
        });
        return;
      }
      canonicalLocalPath = validated.canonicalPath;
    }

    try {
      const installOptions = canonicalLocalPath !== undefined
        ? { localPath: canonicalLocalPath }
        : { packageName: trimmedPackage, version: version?.trim() };

      const discovered = await loader.installPlugin(installOptions);

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Fix the offending parameter to satisfy the constraint stated in the error message (type, range, or allowed values), then retry.
2. Refer to the route's request validation in the named file and the shared validators for the accepted format.

When it happens

Trigger: Thrown at server/src/routes/plugins.ts:1176 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/95c83c13898c979f. Report an issue: GitHub.