paperclipai/paperclip · error · AuthorizationError

invalid_handle

invalid_handle

Error message

unknown or stale lease handle

What it means

AuthorizationError('invalid_handle') from authorizeRemoval: no lease in the registry has a handle that timing-safely equals the requested handle. The handle is unknown or refers to a lease that has since been removed/expired, so no lease can be resolved for the remove request.

Source

Thrown at packages/tailscale-https-broker/src/authorization.ts:78

  const ab = Buffer.from(a, "utf8");
  const bb = Buffer.from(b, "utf8");
  if (ab.byteLength !== bb.byteLength) return false;
  return timingSafeEqual(ab, bb);
}

/**
 * Resolve the lease a `remove` request is authorized to act on. Requires an
 * exact handle match AND that the requesting peer + runtime UUID match the
 * lease bound at expose time. Runtime A can never remove runtime B's listener.
 */
export function authorizeRemoval(
  leases: readonly LeaseRecord[],
  request: { runtimeId: string; handle: string },
  peer: PeerCredentials,
): LeaseRecord {
  const lease = leases.find((entry) => handlesEqual(entry.handle, request.handle));
  if (!lease) {
    throw new AuthorizationError("invalid_handle", "unknown or stale lease handle");
  }
  if (lease.runtimeId !== request.runtimeId) {
    throw new AuthorizationError("listener_ownership_mismatch", "runtime id does not match lease");
  }
  if (lease.peerUid !== peer.uid || lease.peerGid !== peer.gid) {
    throw new AuthorizationError("listener_ownership_mismatch", "peer identity does not match lease");
  }
  return lease;
}

View on GitHub (pinned to 120ae5428f)

Solutions

1. Acquire a new lease; the handle is unknown or expired.

When it happens

Trigger: Thrown at packages/tailscale-https-broker/src/authorization.ts:78 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/77940ca57923ae12. Report an issue: GitHub.