paperclipai/paperclip · error · Error

Managed installs require Node.js 20 or newer (found ${proces

Error message

Managed installs require Node.js 20 or newer (found ${process.version}).

What it means

Thrown by assertSupportedNodeVersion (install.ts:89) when the running Node.js major version is below 20 or unparseable. The managed installer requires Node 20+ for the runtime APIs and ESM features it relies on; older versions are rejected before any install work begins.

Source

Thrown at cli/src/commands/install.ts:89

      const dependencies = packageJson[section];
      if (!dependencies || typeof dependencies !== "object") continue;
      for (const dependencyName of Object.keys(dependencies)) {
        if (dependencyName.startsWith("@paperclipai/")) visit(dependencyName);
      }
    }
    visiting.delete(packageName);
    visited.add(packageName);
    ordered.push(entry);
  };

  visit("@paperclipai/server");
  return ordered;
}

function assertSupportedNodeVersion(): void {
  const major = Number(process.versions.node.split(".")[0]);
  if (!Number.isFinite(major) || major < 20) {
    throw new Error(`Managed installs require Node.js 20 or newer (found ${process.version}).`);
  }
}

export function resolveNpmInstallRequest(options: InstallOptions): {
  spec: string;
  channel: InstallChannel;
} {
  if (options.canary && options.version) throw new Error("Choose either --canary or --version, not both.");
  if (options.version) {
    const version = options.version.trim();
    if (!EXACT_VERSION_PATTERN.test(version)) {
      throw new Error(`--version requires an exact published version, received '${options.version}'.`);
    }
    return { spec: version, channel: "pinned" };
  }
  return options.canary ? { spec: "canary", channel: "canary" } : { spec: "latest", channel: "latest" };
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Upgrade to Node 20 or newer (prefer an LTS): nvm install 20 && nvm use 20, or update fnm/volta.
2. In CI, set the image/node-version to >=20.
3. Confirm with `node --version` before re-running the installer.

Example fix

# before
node --version  # v18.x
# after
nvm install 20 && nvm use 20 && node --version  # v20.x

function assertNode20(): void {
  const major = Number(process.versions.node.split('.')[0]);
  if (!Number.isFinite(major) || major < 20) {
    throw new Error(`Node 20+ required, found ${process.version}.`);
  }
}

assertNode20();

function isNodeVersionSupported(): boolean {
  const major = Number(process.versions.node.split('.')[0]);
  return Number.isFinite(major) && major >= 20;
}

When it happens

Trigger: Invoking the managed installer under Node 18.x, 16.x, or older. process.versions.node is split on '.' and the major is parsed; non-finite or < 20 fails.

Common situations: A system with an outdated default Node, an nvm/fnm shell that did not switch, a CI image pinned to an old Node LTS, or a container with the wrong tag.

Related errors

• --version is only supported for npm package installs, not lo
• Approval request failed.
• Invalid --secret-value "${raw}". Use key=value.
• ${error instanceof Error ? error.message : String(error)}\n$
• Circular workspace dependency while staging ${packageName}.

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/bf048e7206949e01. Report an issue: GitHub.