dropping 1 event whose serialized envelope exceeds maxBodyBy

Error message

dropping 1 event whose serialized envelope exceeds maxBodyBytes (${this.caps.maxBodyBytes} bytes); event="${chunk[0]?.name}"

What it means

TelemetryClient splits event batches by serialized byte size (binary halving) so each POST stays within caps.maxBodyBytes (default 512 KiB). A batch of one event that still exceeds the cap cannot be split further, so the event is dropped and this warning logged — deliberate fail-loud data loss of exactly one event.

Source

Thrown at packages/shared/src/telemetry/client.ts:190

   */
  private chunkForSend(events: TelemetryEvent[]): TelemetryEvent[][] {
    const maxCount = Math.max(1, this.caps.maxEventsPerBatch);
    const out: TelemetryEvent[][] = [];
    for (let i = 0; i < events.length; i += maxCount) {
      this.splitByBytes(events.slice(i, i + maxCount), out);
    }
    return out;
  }

  private splitByBytes(chunk: TelemetryEvent[], out: TelemetryEvent[][]): void {
    if (chunk.length === 0) return;
    const bytes = this.serializedBytes(this.buildEnvelope(chunk));
    if (bytes <= this.caps.maxBodyBytes) {
      out.push(chunk);
      return;
    }
    if (chunk.length === 1) {
      this.warn(
        Number.isFinite(bytes)
          ? `dropping 1 event whose serialized envelope exceeds maxBodyBytes (${this.caps.maxBodyBytes} bytes); event="${chunk[0]?.name}"`
          : `dropping 1 event with a non-serializable dimension (circular reference?); event="${chunk[0]?.name}"`,
      );
      return;
    }
    const mid = Math.ceil(chunk.length / 2);
    this.splitByBytes(chunk.slice(0, mid), out);
    this.splitByBytes(chunk.slice(mid), out);
  }

  private buildEnvelope(events: TelemetryEvent[], batchId?: string): TelemetryEventEnvelope {
    const state = this.getState();
    return {
      app: this.config.app ?? "paperclip",
      schemaVersion: this.config.schemaVersion ?? "1",
      installId: state.installId,
      version: this.version,

View on GitHub (pinned to 120ae5428f)

Solutions

Take the event name from the warning and truncate its large dimension at the emit site to a bounded preview (e.g. first 2 KB).
Emit a reference (URL, artifact id, hash) instead of the blob itself and store the payload out-of-band.
Raise caps.maxBodyBytes in telemetry config if the collector accepts larger bodies.
Add a unit test asserting serialized event size stays under the cap for every emit site.

Example fix

// before
telemetry.emit({ name: 'agent_message', dims: { text: message } });

// after
const preview = message.length > 2000 ? message.slice(0, 2000) + '…' : message;
telemetry.emit({ name: 'agent_message', dims: { text: preview, fullLength: message.length } });

Defensive patterns

Strategy: validation

Validate before calling

const MAX_TELEMETRY_BYTES = 512 * 1024; // keep in sync with caps.maxBodyBytes

function assertEventSize(event: TelemetryEvent): void {
  const bytes = Buffer.byteLength(JSON.stringify(event));
  if (bytes > MAX_TELEMETRY_BYTES) {
    throw new Error(
      `Telemetry event ${event.name} is ${bytes} bytes (cap ${MAX_TELEMETRY_BYTES}); truncate dimensions at the emit site`,
    );
  }
}

Prevention

Truncate every free-text dimension at emit time to a fixed budget (e.g. 2 KB).
Store large payloads out-of-band and emit references (URL/artifact id/hash).
Alert on any 'dropping 1 event' warn — each is silent data loss.
Add unit tests bounding serialized event size per emit site.

When it happens

Trigger: An emitted TelemetryEvent whose serialized envelope alone exceeds maxBodyBytes — a dimension carrying a very large string (full file contents, a giant error message or HTTP body, embedded logs).

Common situations: Instrumenting prompts/model outputs into events verbatim; serializing response bodies or stack traces with megabytes of text; reusing log lines as dimensions; lowering maxBodyBytes without auditing emitters.

Related errors

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