paperclipai/paperclip · error

Unsupported Paperclip operation

Error message

Unsupported Paperclip operation ${tool}

What it means

Unsupported-operation guard in the Codex ACPX driver's tool bridge: a Paperclip tool invocation arrived whose tool name is not among the operations the Codex ACPX session can bridge, so the session rejects it instead of dispatching blindly. Generic validation helper — the input at fault is the unknown/unregistered tool name in the incoming call, typically after a runner/adapter version mismatch or a typo'd tool registration.

Solutions

1. Check the tool name in the message against the operations the CodexAcpxSession registers in its bridge.
2. Align runner and adapter versions so both sides advertise the same tool set.
3. Register an implementation for the missing tool or remove it from the caller's advertised capabilities.

When it happens

Trigger: Thrown at packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts:1121 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/4e456cb8da61025a. Report an issue: GitHub.

Appendix: source

Thrown at packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts:1121

          // provider turn completes successfully. A failed or interrupted
          // retry must leave the last completed owner recoverable.
          this.#pendingSemanticTransfer = {
            result: structuredClone(validation.result),
            fingerprint,
            callId: call.callId,
            turnId,
          };
        } else {
          this.#semanticResult = structuredClone(validation.result);
          this.#semanticFingerprint = fingerprint;
          this.#semanticCallId = call.callId;
          this.#semanticTurnId = turnId;
        }
      }
      return { accepted: true, feedback };
    }
    if (!this.#dynamicToolHandler) {
      throw new Error(`Unsupported Paperclip operation ${tool}`);
    }
    return await this.#dynamicToolHandler({
      tool,
      callId: call.callId,
      providerSessionId: this.#host.identity().agentSessionId,
      turnId,
      arguments: structuredClone(call.arguments),
      signal: call.signal,
    });
  }

  async read(): Promise<Record<string, unknown>> {
    return {
      identity: this.#host.identity(),
      binding: this.#host.binding(),
      status: await this.#host.status(),
    };
  }

View on GitHub (pinned to 3f1d897a7c)