paperclipai/paperclip · error · Error

Native provider is not available through the local runnerd…

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.

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.

Related errors

External chat card action type is invalid

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

Appendix: source

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

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