Remote runner workspace authority requires a runnerd transpo

Error message

Remote runner workspace authority requires a runnerd transport

What it means

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.

Source

Thrown at packages/paperclip-runner/src/backends/codex-native-backend.ts:109

        displayName: `${input.provider.agent === "claude" ? "Claude" : "Codex"} via ACPX`,
        version: "0.13.1",
      };
    default:
      throw new Error(
        "Native provider is not available through the local runnerd transport",
      );
  }
}

function createTransportBackedNativeSessionBackend(
  input: NativeExecutionInput,
  options: CodexNativeSessionBackendOptions,
): NativeSessionBackend {
  if (
    options.workingDirectoryAuthority === "remote_runner" &&
    !options.transportFactory
  ) {
    throw new Error(
      "Remote runner workspace authority requires a runnerd transport",
    );
  }
  const driverIdentity = transportDriverIdentity(input);
  const isCodex = input.provider.kind === "codex";
  const supportsCollaborativePlanning =
    isCodex ||
    input.provider.kind === "opencode" ||
    input.provider.kind === "acpx";
  if (
    input.provider.kind === "codex" &&
    input.provider.approvalPolicy !== undefined &&
    input.provider.approvalPolicy !== "never"
  ) {
    throw new Error(
      "paperclip_runner_codex_permission_mode_unqualified: set codexPermissionMode to never before starting or recovering this native run",
    );
  }

View on GitHub (pinned to 01ad858492)

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.

Example fix

// before
createCodexNativeSessionBackend({ workingDirectoryAuthority: "remote_runner" });
// after
createCodexNativeSessionBackend({
  workingDirectoryAuthority: "remote_runner",
  transportFactory: (input) => createRunnerdTransport(input),
});

Defensive patterns

Strategy: validation

Validate before calling

if (options.workingDirectoryAuthority === "remote_runner" && !options.transportFactory) {
  throw new Error("remote_runner authority requires transportFactory");
}

Type guard

function hasTransportFor(o) {
  return o.workingDirectoryAuthority !== "remote_runner" || typeof o.transportFactory === "function";
}

Try / catch

try {
  const backend = createCodexNativeSessionBackend(options);
} catch (err) {
  if (err.message.includes("requires a runnerd transport")) {
    console.error("Provide transportFactory or use local workspace authority");
    process.exit(1);
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: Calling createRunnerdNativeSessionBackend or createCodexNativeSessionBackend with options.workingDirectoryAuthority set to 'remote_runner' while options.transportFactory is undefined or omitted.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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