paperclipai/paperclip · error · Error

Native provider is not available through the local runnerd t

Error message

Native provider is not available through the local runnerd transport

What it means

transportDriverIdentity's switch has cases only for codex, opencode, claude_managed, aws_agentcore, and acpx provider kinds. Any other provider.kind (including an unknown or unset one, hitting the default branch) throws a plain Error: that native provider kind cannot be served through the local runnerd transport backed by CodexAppServerDriver.

Source

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

    case "aws_agentcore":
      return {
        kind: "aws_agentcore_harness_api",
        displayName: "AWS AgentCore Harness",
        version: input.provider.agentCoreProfile.qualificationRevision,
      };
    case "acpx":
      if (input.provider.agent === "pi") {
        throw new Error(
          "Native ACPX backend for pi is unavailable until descriptor-confined verified launch is implemented",
        );
      }
      return {
        kind: "acpx_runtime",
        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);

View on GitHub (pinned to 01ad858492)

Solutions

Set provider.kind to one of the supported values: 'codex', 'opencode', 'claude_managed', 'aws_agentcore', or 'acpx'.
Fix the provider descriptor source so kind is populated and spelled exactly as in the discriminated union (case-sensitive).
If a new provider kind must be supported, add a case to transportDriverIdentity in codex-native-backend.ts returning its driver identity.
Validate/parse the provider input against the NativeExecutionInput contract before invoking the native backend factory to catch bad kinds early.

Example fix

// before
const input = { provider: { kind: undefined, model: "x" } }; // hits default branch, throws
// after
const input = { provider: { kind: "codex", model: "x" } }; // supported kind

Defensive patterns

Strategy: type-guard

Validate before calling

const SUPPORTED_KINDS = ["codex", "opencode", "claude_managed", "aws_agentcore", "acpx"];
function isSupportedNativeKind(provider) {
  return SUPPORTED_KINDS.includes(provider?.kind);
}
// before calling:
if (!isSupportedNativeKind(input.provider)) {
  throw new Error(`provider.kind must be one of ${SUPPORTED_KINDS.join(", ")}, got ${JSON.stringify(input.provider?.kind)}`);
}

Type guard

function isNativeExecutionProvider(p) {
  return p !== null && typeof p === "object"
    && ["codex", "opencode", "claude_managed", "aws_agentcore", "acpx"].includes(p.kind);
}

Try / catch

try {
  const backend = createTransportBackedNativeSessionBackend(input, options);
} catch (err) {
  if (/not available through the local runnerd transport/.test(err.message)) {
    console.error(`Unsupported provider.kind=${JSON.stringify(input.provider?.kind)}; supported: codex, opencode, claude_managed, aws_agentcore, acpx.`);
    return null;
  }
  throw err;
}

Prevention

Always populate provider.kind with an exact, case-sensitive supported value.
Validate/parse provider descriptors against the NativeExecutionInput discriminated union before invoking the backend.
Watch for typos and casing mistakes like 'Codex' or 'codex_native' that fall into the default branch.
When adding a new provider kind, update transportDriverIdentity's switch in the same change and add a test for it.
Avoid passing legacy/generic provider objects into the native backend factory; construct typed inputs instead.

When it happens

Trigger: Calling createTransportBackedNativeSessionBackend (or driverIdentity) with input.provider.kind outside the five supported values — e.g. kind is undefined/null, a typo like 'codex-native' or 'Codex', or a newly added provider kind that codex-native-backend has not been extended to handle.

Common situations: A missing or malformed provider descriptor so kind falls through as undefined; a new provider kind added to the type union but not to this switch; case-sensitivity mistakes in serialized config; passing a generic/legacy provider object into the native backend factory.

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