paperclipai/paperclip · error · Error

Managed installs require Node.js ${MINIMUM_NODE_VERSION} or

Error message

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

What it means

Thrown by assertSupportedNodeVersion(), called as the first step of installCommand (cli/src/commands/install.ts:362). Paperclip's managed installer requires Node.js 24.11.0 or newer (MINIMUM_NODE_VERSION from @paperclipai/shared/node-version); isSupportedNodeVersion() parses process.versions.node as semver and rejects anything older or unparseable. The guard protects the install payload, which depends on Node 24 runtime behavior. The offending process.version is included in the message.

Source

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

    for (const section of ["dependencies", "optionalDependencies", "peerDependencies"] as const) {
      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 {
  if (!isSupportedNodeVersion(process.versions.node)) {
    throw new Error(`Managed installs require Node.js ${MINIMUM_NODE_VERSION} 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 a7e689b3c3)

Solutions

Upgrade Node to >= 24.11.0 (e.g. `nvm install 24.11.0 && nvm use 24.11.0`) and retry `paperclipai install`
Check `node --version` in the exact shell/PATH the install runs from (wrappers, CI steps, service definitions)
In CI, bump the base image or setup-node action to Node 24+
If Node cannot be upgraded here, run the CLI from a prebuilt runtime that bundles a supported Node, or defer the managed install

Example fix

# before
$ node --version
v22.23.0
$ paperclipai install
Error: Managed installs require Node.js 24.11.0 or newer (found v22.23.0).

# after
$ nvm install 24.11.0 && nvm use 24.11.0
$ paperclipai install

Defensive patterns

Strategy: validation

Validate before calling

import { isSupportedNodeVersion, MINIMUM_NODE_VERSION } from '@paperclipai/shared/node-version';

if (!isSupportedNodeVersion(process.versions.node)) {
  console.error(`Node >= ${MINIMUM_NODE_VERSION} required (found ${process.version}); aborting before install.`);
  process.exit(1);
}
await installCommand(options);

Try / catch

Catch in the CLI wrapper and print an upgrade hint (`node --version`, `nvm install 24.11.0`) instead of a stack trace.

Prevention

Pin engines.node >= 24.11.0 in wrapper packages so npm warns at install time
Assert `node --version` in CI before invoking paperclipai install
Set the nvm default to a 24.x line so new shells get a supported runtime

When it happens

Trigger: Running `paperclipai install` (installCommand) under Node.js < 24.11.0, or under a runtime whose process.versions.node cannot be parsed (e.g. 'unknown'). Every managed-install entry path hits this guard before any npm/git payload work runs.

Common situations: System Node on an LTS line older than 24.11.0 (v20/v22); nvm default pointing at a stale toolchain; CI images pinned to node:20 or node:22; a wrapper script resolving a different `node` from PATH than the interactive shell.

Related errors

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