runner_remote_provider_artifact_incompatible: ${label} path

Error message

runner_remote_provider_artifact_incompatible: ${label} path belongs to the controller host

What it means

Guard against accidentally shipping controller-host-specific provider artifact paths (macOS /Users/... or Windows C:\Users\...) to a remote runner. A provider path pointing at the controller host cannot work on the remote runner host, so the transport fails fast with a labeled, incompatible-path error.

Source

Thrown at packages/paperclip-runner/src/live/runnerd-codex-transport.ts:4247

            opencodeExecutable!,
          )
        : undefined;
    if (
      this.options.runnerFilesystemRoot &&
      (provider === "opencode" || provider === "acpx")
    ) {
      const providerPaths = [
        ["provider Node", providerNodeCommand],
        ["OpenCode proxy", opencodeProxyPath],
        ["ACPX sidecar", acpxSidecarPath],
        ["OpenCode executable", opencodeExecutable ?? "opencode"],
      ] as const;
      for (const [label, candidate] of providerPaths) {
        if (
          candidate.startsWith("/Users/") ||
          /^[A-Za-z]:\\\\Users\\\\/.test(candidate)
        ) {
          throw new Error(
            `runner_remote_provider_artifact_incompatible: ${label} path belongs to the controller host`,
          );
        }
      }
      if (!this.options.providerNodeCommand) {
        throw new Error(
          "runner_remote_provider_artifact_incompatible: remote JS provider omitted its provider-pack Node executable",
        );
      }
      if (provider === "opencode" && !this.options.opencodeProxyPath) {
        throw new Error(
          "runner_remote_provider_artifact_incompatible: remote OpenCode omitted its packaged proxy",
        );
      }
      if (provider === "acpx" && !this.options.acpxSidecarPath) {
        throw new Error(
          "runner_remote_provider_artifact_incompatible: remote ACPX omitted its packaged sidecar",
        );

View on GitHub (pinned to 01ad858492)

Solutions

Point provider paths at locations valid on the remote runner host, not the controller host
Resolve provider paths relative to the runner's root/workdir instead of absolute controller paths
Move provider artifacts into a shared/remotely-accessible location referenced by a runner-local path
Scrub /Users/... or C:\Users\... defaults from your provider configuration

Example fix

// before
const providerPaths = { codexHome: "/Users/alice/.codex" };
// after
const providerPaths = { codexHome: resolve(this.#root, "provider/codex-home") };

Defensive patterns

Strategy: validation

Validate before calling

const hostUserPath = /(^\/Users\/)|(^[A-Za-z]:\\\\Users\\\\)/;
for (const p of Object.values(providerPaths)) {
  if (hostUserPath.test(String(p))) {
    throw new Error(`provider path ${p} is controller-host-specific; use a runner-local path`);
  }
}

Type guard

null

Try / catch

try {
  transport = new RunnerdCodexTransport(options);
} catch (err) {
  if (err instanceof Error && err.message.includes("runner_remote_provider_artifact_incompatible")) {
    options.providerPaths = remapPathsToRunnerLocal(options.providerPaths);
    transport = new RunnerdCodexTransport(options);
  } else throw err;
}

Prevention

Never hardcode absolute home-directory paths in provider config
Resolve provider artifacts relative to the runner root
Validate all provider paths against host-specific patterns in CI config tests

When it happens

Trigger: Configuring providerPaths (provider binary/state/session paths) with values that start with /Users/ or match ^[A-Za-z]:\\Users\\ while constructing a remote runner transport.

Common situations: Hardcoding the developer's macOS home directory path in provider config; copying local codex session/state paths from the controller into remote runner options; running the controller on a laptop and the runner on a container/CI host.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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