paperclipai/paperclip · error

assigned native MCP launch binding is unavailable

Error message

assigned native MCP launch binding is unavailable

What it means

Availability guard in AcpxRuntimeHost.open: nativeMcpLaunchBinding(options.environment) returned nothing usable, meaning the environment does not provide the native MCP launch binding the ACPX runtime host requires to start, so open() fails fast instead of launching a runtime without its native MCP server. Generic validation — the input at fault is the environment descriptor lacking the binding (missing config, unsupported agent/environment combination).

Solutions

1. Ensure the runtime environment descriptor includes a native MCP launch binding before calling open().
2. Check that the selected agent/environment combination supports native MCP launch (pi, for example, is explicitly unavailable).
3. Fix the binding resolution (nativeMcpLaunchBinding) if a valid binding was expected for this environment.

When it happens

Trigger: Thrown at packages/paperclip-runner/src/drivers/acpx/runtime-host.ts:300 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at packages/paperclip-runner/src/drivers/acpx/runtime-host.ts:300

    this.#claudeSkillNames = [...input.claudeSkillNames];
  }

  static async open(
    options: OpenAcpxRuntimeHostOptions,
    dependencies: AcpxRuntimeHostDependencies,
  ): Promise<AcpxRuntimeHost> {
    options.signal?.throwIfAborted();
    if (options.agent === "pi") {
      throw new Error(
        "ACPX pi is unavailable until its runtime has descriptor-confined verified launch",
      );
    }
    const nativeMcp = nativeMcpLaunchBinding(options.environment);
    if (nativeMcp?.name === "paperclip") {
      throw new Error("assigned native MCP name conflicts with the task bridge");
    }
    if (options.runtimeContext?.mcp.bindingId && !nativeMcp) {
      throw new Error("assigned native MCP launch binding is unavailable");
    }
    const profile = resolveQualifiedAcpxProfile(options.agent, options.model);
    const binding = await runAbortableAdmissionStage(
      options.signal,
      () =>
        createAcpxRecoveryBinding({
          runtimeDirectory: options.runtimeDirectory,
          normalizedSessionId: options.normalizedSessionId,
          workingDirectory: options.workingDirectory,
          profile,
          requestedModel: options.model,
          permissionMode: options.permissionMode,
        }),
      dependencies.retainAdmissionCleanup,
    );
    if (options.expectedIdentity) {
      verifyExpectedAcpxIdentity(options.expectedIdentity, binding, null);
    }

View on GitHub (pinned to 3f1d897a7c)