paperclipai/paperclip · error · ProtocolError

unknown_operation

unknown_operation

Error message

unknown operation: ${String(op)}

What it means

Operation dispatch guard in decodeRequest: the `op` field is not one of reserve/expose/remove/list. ProtocolError('unknown_operation') rejects the frame after requestId was validated, so a malformed or future op cannot reach the command handlers.

Source

Thrown at packages/tailscale-https-broker/src/protocol.ts:111

      "malformed_request",
      `invalid JSON: ${(error as Error).message}`,
    );
  }

  const obj = asObject(parsed);

  if (obj.v !== BROKER_PROTOCOL_VERSION) {
    throw new ProtocolError(
      "unsupported_version",
      `unsupported protocol version: ${String(obj.v)}`,
    );
  }

  const requestId = requireStringField(obj, "requestId", REQUEST_ID_RE, "malformed_request", null);

  const op = obj.op;
  if (op !== "reserve" && op !== "expose" && op !== "remove" && op !== "list") {
    throw new ProtocolError("unknown_operation", `unknown operation: ${String(op)}`, requestId);
  }

  if (op === "list") {
    assertExactKeys(obj, ["v", "op", "requestId"], requestId);
    return { op: "list", requestId };
  }

  if (op === "remove" || op === "expose") {
    assertExactKeys(obj, ["v", "op", "requestId", "runtimeId", "handle"], requestId);
    const runtimeId = requireStringField(obj, "runtimeId", UUID_RE, "invalid_runtime_id", requestId);
    const handle = requireStringField(obj, "handle", HANDLE_RE, "malformed_request", requestId);
    return { op, requestId, runtimeId, handle };
  }

  // reserve
  assertExactKeys(obj, ["v", "op", "requestId", "runtimeId", "listeners"], requestId);
  const runtimeId = requireStringField(obj, "runtimeId", UUID_RE, "invalid_runtime_id", requestId);
  const rawListeners = obj.listeners;

View on GitHub (pinned to 120ae5428f)

Solutions

1. Send one of the operations the broker supports; check the client for a typo or version mismatch.

When it happens

Trigger: Thrown at packages/tailscale-https-broker/src/protocol.ts:111 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/e4f8289620be2f3d. Report an issue: GitHub.