{"record":{"id":"49554e2c7ffc3a04","repo":"paperclipai/paperclip","slug":"dropping-1-event-whose-serialized-envelope-exceeds","errorCode":null,"errorMessage":"dropping 1 event whose serialized envelope exceeds maxBodyBytes (${this.caps.maxBodyBytes} bytes); event=\"${chunk[0]?.name}\"","messagePattern":"dropping 1 event whose serialized envelope exceeds maxBodyBytes \\((.+?) bytes\\); event=\"(.+?)\"","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/shared/src/telemetry/client.ts","lineNumber":190,"sourceCode":"   */\n  private chunkForSend(events: TelemetryEvent[]): TelemetryEvent[][] {\n    const maxCount = Math.max(1, this.caps.maxEventsPerBatch);\n    const out: TelemetryEvent[][] = [];\n    for (let i = 0; i < events.length; i += maxCount) {\n      this.splitByBytes(events.slice(i, i + maxCount), out);\n    }\n    return out;\n  }\n\n  private splitByBytes(chunk: TelemetryEvent[], out: TelemetryEvent[][]): void {\n    if (chunk.length === 0) return;\n    const bytes = this.serializedBytes(this.buildEnvelope(chunk));\n    if (bytes <= this.caps.maxBodyBytes) {\n      out.push(chunk);\n      return;\n    }\n    if (chunk.length === 1) {\n      this.warn(\n        Number.isFinite(bytes)\n          ? `dropping 1 event whose serialized envelope exceeds maxBodyBytes (${this.caps.maxBodyBytes} bytes); event=\"${chunk[0]?.name}\"`\n          : `dropping 1 event with a non-serializable dimension (circular reference?); event=\"${chunk[0]?.name}\"`,\n      );\n      return;\n    }\n    const mid = Math.ceil(chunk.length / 2);\n    this.splitByBytes(chunk.slice(0, mid), out);\n    this.splitByBytes(chunk.slice(mid), out);\n  }\n\n  private buildEnvelope(events: TelemetryEvent[], batchId?: string): TelemetryEventEnvelope {\n    const state = this.getState();\n    return {\n      app: this.config.app ?? \"paperclip\",\n      schemaVersion: this.config.schemaVersion ?? \"1\",\n      installId: state.installId,\n      version: this.version,","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/paperclipai/paperclip/blob/120ae5428fa29bee300bcf806491cd4d965fbb7c/packages/shared/src/telemetry/client.ts#L172-L208","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\ntelemetry.emit({ name: 'agent_message', dims: { text: message } });\n\n// after\nconst preview = message.length > 2000 ? message.slice(0, 2000) + '…' : message;\ntelemetry.emit({ name: 'agent_message', dims: { text: preview, fullLength: message.length } });","handlingStrategy":"validation","validationCode":"const MAX_TELEMETRY_BYTES = 512 * 1024; // keep in sync with caps.maxBodyBytes\n\nfunction assertEventSize(event: TelemetryEvent): void {\n  const bytes = Buffer.byteLength(JSON.stringify(event));\n  if (bytes > MAX_TELEMETRY_BYTES) {\n    throw new Error(\n      `Telemetry event ${event.name} is ${bytes} bytes (cap ${MAX_TELEMETRY_BYTES}); truncate dimensions at the emit site`,\n    );\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["telemetry","payload-size","event-drop","limits"],"backgroundTag":"payload-too-large","analyzedSha":"120ae5428fa29bee300bcf806491cd4d965fbb7c","analyzedAt":"2026-08-18T22:49:45.177Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}