{"record":{"id":"d8891705e34129bb","repo":"paperclipai/paperclip","slug":"runner-process-connection-is-required","errorCode":null,"errorMessage":"runner process connection is required","messagePattern":"runner process connection is required","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/control-plane/durable-prp-control-plane.ts","lineNumber":3289,"sourceCode":"  opencodeLaunchProfile?: {\n    command: string;\n    commandSha256: string;\n    proxyScript: string;\n    proxyScriptSha256: string;\n    executable: string;\n    executableSha256: string;\n  };\n  environment?: NodeJS.ProcessEnv;\n  processLauncher?: (spec: RunnerProcessLaunchSpec) => RunnerProcessHandle;\n  diagnosticsDirectory?: string;\n}): RunnerProcessHandle {\n  const connection =\n    options.connection ??\n    (options.connectUrl\n      ? { mode: \"connect\" as const, connectUrl: options.connectUrl }\n      : null);\n  if (connection === null)\n    throw new Error(\"runner process connection is required\");\n  const connectionArgs =\n    connection.mode === \"connect\"\n      ? [\n          \"--connect-url\",\n          connection.connectUrl,\n          ...(connection.caBundlePath === undefined\n            ? []\n            : [\"--ca-bundle-path\", connection.caBundlePath]),\n        ]\n      : [\n          \"--listen-address\",\n          connection.listenAddress,\n          \"--listen-port\",\n          String(connection.listenPort),\n          \"--listen-path\",\n          connection.listenPath,\n        ];\n  const args = [","sourceCodeStart":3271,"sourceCodeEnd":3307,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/control-plane/durable-prp-control-plane.ts#L3271-L3307","documentation":"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.","triggerScenarios":"Invoking the runner-process factory with options lacking both connection and connectUrl, e.g. a config object that only sets spawn/executable options.","commonSituations":"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.","solutions":["Pass options.connectUrl with the control-plane connect URL.","Pass a pre-built options.connection object ({ mode: \"connect\", connectUrl } or equivalent spawn spec).","Fix the config loading so connectUrl is populated from env/config before the runner is constructed.","Fail fast in your own bootstrap code if connectUrl is missing rather than reaching this error."],"exampleFix":"// before\nstartRunner({ executable: runnerPath });\n// after\nstartRunner({ executable: runnerPath, connectUrl: process.env.RUNNER_CONNECT_URL });","handlingStrategy":"validation","validationCode":"if (options.connection == null && !options.connectUrl) {\n  throw new Error(\"runner connectUrl or connection must be configured\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  startRunner(options);\n} catch (err) {\n  if (err.message === \"runner process connection is required\") {\n    // surface a config error pointing at connectUrl\n  } else throw err;\n}","preventionTips":["Validate runner config (connectUrl/connection) at startup before spawning.","Keep connectUrl in one config source and assert it non-empty.","Fail fast in CLI flag parsing when --connect-url is absent."],"tags":["configuration","runner","missing-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}