paperclipai/paperclip · error

runner process connection is required

Error message

runner process connection is required

What it means

The runner process launcher requires a connection specification. Callers must pass either an existing options.connection or a connectUrl from which a { mode: "connect", connectUrl } connection is derived. If neither is provided, there is no way to attach the runner to a control plane, so construction fails immediately.

Source

Thrown at packages/paperclip-runner/src/control-plane/durable-prp-control-plane.ts:3289

  opencodeLaunchProfile?: {
    command: string;
    commandSha256: string;
    proxyScript: string;
    proxyScriptSha256: string;
    executable: string;
    executableSha256: string;
  };
  environment?: NodeJS.ProcessEnv;
  processLauncher?: (spec: RunnerProcessLaunchSpec) => RunnerProcessHandle;
  diagnosticsDirectory?: string;
}): RunnerProcessHandle {
  const connection =
    options.connection ??
    (options.connectUrl
      ? { mode: "connect" as const, connectUrl: options.connectUrl }
      : null);
  if (connection === null)
    throw new Error("runner process connection is required");
  const connectionArgs =
    connection.mode === "connect"
      ? [
          "--connect-url",
          connection.connectUrl,
          ...(connection.caBundlePath === undefined
            ? []
            : ["--ca-bundle-path", connection.caBundlePath]),
        ]
      : [
          "--listen-address",
          connection.listenAddress,
          "--listen-port",
          String(connection.listenPort),
          "--listen-path",
          connection.listenPath,
        ];
  const args = [

View on GitHub (pinned to 01ad858492)

Solutions

1. Pass options.connectUrl with the control-plane connect URL.
2. Pass a pre-built options.connection object ({ mode: "connect", connectUrl } or equivalent spawn spec).
3. Fix the config loading so connectUrl is populated from env/config before the runner is constructed.
4. Fail fast in your own bootstrap code if connectUrl is missing rather than reaching this error.

Example fix

// before
startRunner({ executable: runnerPath });
// after
startRunner({ executable: runnerPath, connectUrl: process.env.RUNNER_CONNECT_URL });

if (options.connection == null && !options.connectUrl) {
  throw new Error("runner connectUrl or connection must be configured");
}

try {
  startRunner(options);
} catch (err) {
  if (err.message === "runner process connection is required") {
    // surface a config error pointing at connectUrl
  } else throw err;
}

When it happens

Trigger: Invoking the runner-process factory with options lacking both connection and connectUrl, e.g. a config object that only sets spawn/executable options.

Common situations: Missing connect-url in environment/config after migrating to a connect-based setup; constructing the launcher programmatically and forgetting the connection field; a config loader that drops null connectUrl.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Installing or updating Paperclip requires Node.js ${MINIMUM_
• Paperclip returned no result while ${action}.
• No available loopback port found at or above ${preferredPort
• Paperclip Runner currently supports Codex only with codexPer
• unknown Runner live eval candidate: ${id}

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/d8891705e34129bb. Report an issue: GitHub.