paperclipai/paperclip · error

runner_remote_provider_artifact_incompatible

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.

Solutions

1. Point provider paths at locations valid on the remote runner host, not the controller host
2. Resolve provider paths relative to the runner's root/workdir instead of absolute controller paths
3. Move provider artifacts into a shared/remotely-accessible location referenced by a runner-local path
4. 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") };

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`);
  }
}

null

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;
}

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

• A trusted viewer build is required for public chat reports
• ACPX provider package manifest must be an explicit…
• ACPX provider package root must be an explicit normalized…
• ACPX runtime executable must be a bounded executable file
• agent_authorization_required

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

Appendix: source

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

            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 3f1d897a7c)