{"record":{"id":"5bd965af9544c979","repo":"paperclipai/paperclip","slug":"remote-runner-workspace-authority-requires-a-runne","errorCode":null,"errorMessage":"Remote runner workspace authority requires a runnerd transport","messagePattern":"Remote runner workspace authority requires a runnerd transport","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/backends/codex-native-backend.ts","lineNumber":109,"sourceCode":"        displayName: `${input.provider.agent === \"claude\" ? \"Claude\" : \"Codex\"} via ACPX`,\n        version: \"0.13.1\",\n      };\n    default:\n      throw new Error(\n        \"Native provider is not available through the local runnerd transport\",\n      );\n  }\n}\n\nfunction createTransportBackedNativeSessionBackend(\n  input: NativeExecutionInput,\n  options: CodexNativeSessionBackendOptions,\n): NativeSessionBackend {\n  if (\n    options.workingDirectoryAuthority === \"remote_runner\" &&\n    !options.transportFactory\n  ) {\n    throw new Error(\n      \"Remote runner workspace authority requires a runnerd transport\",\n    );\n  }\n  const driverIdentity = transportDriverIdentity(input);\n  const isCodex = input.provider.kind === \"codex\";\n  const supportsCollaborativePlanning =\n    isCodex ||\n    input.provider.kind === \"opencode\" ||\n    input.provider.kind === \"acpx\";\n  if (\n    input.provider.kind === \"codex\" &&\n    input.provider.approvalPolicy !== undefined &&\n    input.provider.approvalPolicy !== \"never\"\n  ) {\n    throw new Error(\n      \"paperclip_runner_codex_permission_mode_unqualified: set codexPermissionMode to never before starting or recovering this native run\",\n    );\n  }","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/backends/codex-native-backend.ts#L91-L127","documentation":"createTransportBackedNativeSessionBackend validates backend options before constructing the driver. If workingDirectoryAuthority is 'remote_runner' — meaning the workspace files live on a remote runner and must be reached over the wire — a transportFactory must be supplied to create the runnerd transport. Without it there is no way to access the remote workspace, so construction fails fast.","triggerScenarios":"Calling createRunnerdNativeSessionBackend or createCodexNativeSessionBackend with options.workingDirectoryAuthority set to 'remote_runner' while options.transportFactory is undefined or omitted.","commonSituations":"Switching a backend config to remote runner authority (e.g. for cloud runners) without wiring up the runnerd transport factory; a refactor that dropped the transport option; copying backend setup code from a local-authority example where no transport was needed.","solutions":["Provide a transportFactory in the backend options that can create a runnerd transport.","Alternatively set workingDirectoryAuthority to a local mode if the workspace is on the same machine and no transport is needed.","Check the config/loader code that builds CodexNativeSessionBackendOptions to ensure the transport field is populated."],"exampleFix":"// before\ncreateCodexNativeSessionBackend({ workingDirectoryAuthority: \"remote_runner\" });\n// after\ncreateCodexNativeSessionBackend({\n  workingDirectoryAuthority: \"remote_runner\",\n  transportFactory: (input) => createRunnerdTransport(input),\n});","handlingStrategy":"validation","validationCode":"if (options.workingDirectoryAuthority === \"remote_runner\" && !options.transportFactory) {\n  throw new Error(\"remote_runner authority requires transportFactory\");\n}","typeGuard":"function hasTransportFor(o) {\n  return o.workingDirectoryAuthority !== \"remote_runner\" || typeof o.transportFactory === \"function\";\n}","tryCatchPattern":"try {\n  const backend = createCodexNativeSessionBackend(options);\n} catch (err) {\n  if (err.message.includes(\"requires a runnerd transport\")) {\n    console.error(\"Provide transportFactory or use local workspace authority\");\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Keep transportFactory wiring next to the workingDirectoryAuthority setting so they change together.","Add an options validation unit test covering the remote_runner + missing transport combination."],"tags":["configuration","transport","invariant"],"backgroundTag":"missing-required-config-field","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}