paperclipai/paperclip · error

Unsupported Paperclip operation

Error message

Unsupported Paperclip operation

What it means

Thrown by OpenCodeHarnessSession when a tool call arrives that requires dynamic (custom/harness-registered) tool handling but no dynamic tool handler was configured on the session. The driver cannot resolve the call on its own, so it refuses with 'Unsupported Paperclip operation'. This is a programming/configuration error, not a transient failure.

Source

Thrown at packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.ts:939

        });
      }
      this.#emit(
        "item.completed",
        {
          kind: "dynamicToolCall",
          item: {
            type: "tool_result",
            id: call.callId,
            tool_use_id: call.callId,
            result: "Semantic completion accepted.",
          },
        },
        { turnId, itemId: call.callId },
      );
      return { accepted: true };
    }
    if (!this.#dynamicToolHandler)
      throw new Error("Unsupported Paperclip operation");
    try {
      const result = await this.#dynamicToolHandler({
        tool,
        callId: call.callId,
        threadId: this.#providerSessionId,
        turnId,
        arguments: call.arguments,
      });
      this.#emit(
        "item.completed",
        {
          kind: "dynamicToolCall",
          item: {
            type: "tool_result",
            id: call.callId,
            tool_use_id: call.callId,
            result,
          },

View on GitHub (pinned to 01ad858492)

Solutions

1. Register a dynamic tool handler when creating the OpenCodeHarnessSession so incoming custom tool calls can be dispatched.
2. If custom tools are not intended, restrict the agent's tool list/permissions so the model cannot invoke unregistered tools.
3. Check the session construction code for a misspelled or dropped option that leaves dynamicToolHandler undefined.

Example fix

// before
const session = new OpenCodeHarnessSession({ runtime, workspace });

// after
const session = new OpenCodeHarnessSession({
  runtime,
  workspace,
  dynamicToolHandler: async ({ tool, callId, threadId, turnId }) => {
    return dispatchTool(tool, callId, threadId, turnId);
  },
});

if (session.getDynamicToolHandler?.() == null && toolsMayIncludeCustom) {
  throw new Error("Session requires a dynamicToolHandler for custom tools");
}

function hasDynamicToolHandler(s: unknown): s is { dynamicToolHandler: Function } {
  return typeof s === "object" && s !== null && "dynamicToolHandler" in s && typeof (s as any).dynamicToolHandler === "function";
}

try {
  await session.submit(toolCall);
} catch (e) {
  if (e instanceof Error && e.message === "Unsupported Paperclip operation") {
    // rebuild session with dynamicToolHandler registered
  }
  throw e;
}

When it happens

Trigger: A tool invocation is dispatched to the session while this.#dynamicToolHandler is undefined — i.e. the session was created without registering a dynamic tool handler but the model/turn emits a call for a tool that is not one of the driver's built-in tools.

Common situations: Developers spawn an OpenCode server session with default options, then the agent calls a custom tool defined only on the Paperclip side; or a refactor renames/removes the dynamicToolHandler option so it silently defaults to undefined.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Sandbox driver does not support duplex channels for this lea
• Environment driver "${driver.driver}" does not support duple
• ACPX session goal action ${action} is unavailable
• ACPX runtime does not expose session goal controls
• github_attachment_canonical_file_unsupported

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