Hmbown/CodeWhale · error · Error

Import exceeds the event limit, including span events.

Error message

Import exceeds the ${maxEvents.toLocaleString()} event limit, including span events.

What it means

After expanding spans into events, fromOTLP also materializes span events (child records) and re-checks the total event count against maxEvents. If spans plus their span events exceed the cap, the import is rejected — the earlier spans-only check is not sufficient.

Solutions

1. Split the export by trace or time window so total events (spans + span events) fit under maxEvents.
2. Reduce span-event volume in the producer (sample annotations, dedupe exception events).
3. Raise options.maxEvents toward the 250000 maximum if the environment allows it.

Example fix

// before
importTrace(otlpJson, 'trace.json');
// after
importTrace(otlpJson, 'trace.json', { maxEvents: 250000, maxTraces: 8 });

const total = countOtlpSpans(text) + countOtlpSpanEvents(text); // spans + all spans[].events[]
if (total > 250000) throw new Error(`Split export: ${total} events exceeds 250000`);

try {
  traces = importTrace(text, file, { maxEvents: 250000 });
} catch (e) {
  if (e instanceof Error && e.message.includes('including span events')) {
    console.error('Too many span events: split by trace or reduce per-span annotations');
  } else throw e;
}

When it happens

Trigger: Importing an OTLP document whose total events (spans + their events[] entries, each producing a record) grows past maxEvents during the second pass, e.g. spans under the limit individually but each carrying many span events.

Common situations: Verbose instrumentation attaching many annotation events per span; exception events on every failed request; exporting one huge trace with thousands of events per span.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• Import exceeds the event limit.
• Every OTLP span requires traceId and spanId.
• No spans found in resourceSpans[].scopeSpans[].spans[].
• OTLP span : end precedes start.
• This import contains more than

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/72c58efb811b972d. Report an issue: GitHub.

Appendix: source

Thrown at pet/src/core/ingest.ts:212

      contextTokens: numericAttr(a['context.tokens']), contextLimit: numericAttr(a['context.limit']),
      retry: numericAttr(a['retry.count'] ?? a['retry.attempt']), status: otelStatus(s.status),
      latency: Number(end - start) / 1e6, attributes: a,
      sourceId: str(a['whalesong.source_id']), targetId: str(a['whalesong.target_id']), targetType: str(a['whalesong.target_type']),
      links: list(s.links).map(l => ({ traceId: l.traceId, spanId: l.spanId, attributes: attributes(l.attributes) })),
      payload: a['gen_ai.input.messages'] !== undefined || a['gen_ai.output.messages'] !== undefined ? {
        request: a['gen_ai.input.messages'], response: a['gen_ai.output.messages'],
      } : undefined,
      raw: rec,
    };
    events.push(e);
    for (const [i, record] of list(s.events).entries()) {
      const ea = attributes(record.attributes), time = Number(ns(record.timeUnixNano, 'event.timeUnixNano') - origin) / 1e6;
      const ename = String(record.name ?? 'span event');
      events.push({ schemaVersion: 1, id: `${s.spanId}/event/${i}`, traceId: s.traceId, parentId: s.spanId,
        startTime: time, endTime: time, agentId: e.agentId, name: ename, category: categoryFor(ename, ea),
        status: ename === 'exception' ? 'error' : 'unknown', attributes: ea, raw: { event: record, spanId: s.spanId, resource: rec.resource, scope: rec.scope } });
    }
    if (events.length > maxEvents) throw new Error(`Import exceeds the ${maxEvents.toLocaleString()} event limit, including span events.`);
  }
  return { events, origins: new Map([...bases].map(([k, v]) => [k, v.toString()])), warnings };
}

/** Parse strictly: malformed lines or duplicate identities never disappear silently. */
export function importTrace(text: string, filename = 'Imported trace', options: ImportOptions = {}): Trace[] {
  const mode = options.privacy ?? 'redact', maxEvents = options.maxEvents ?? 250_000;
  if (!['redact', 'metadata', 'retain'].includes(mode)) throw new Error('Unknown privacy mode.');
  const maxTraces = options.maxTraces ?? 8;
  if (!Number.isInteger(maxEvents) || maxEvents < 1 || maxEvents > 250_000) throw new Error('maxEvents must be in [1, 250000].');
  if (!Number.isInteger(maxTraces) || maxTraces < 1 || maxTraces > 64) throw new Error('maxTraces must be in [1, 64].');
  if (new TextEncoder().encode(text).length > (options.maxBytes ?? 64 * 1024 * 1024)) throw new Error('File exceeds the 64 MiB MVP import limit. Split the export by trace.');
  const trimmed = text.replace(/^\uFEFF/, '').trim();
  if (!trimmed) throw new Error('The trace file is empty.');
  let document: unknown;
  try { document = JSON.parse(trimmed); }
  catch {
    document = trimmed.split(/\r?\n/).filter(l => l.trim()).map((line, i) => {

View on GitHub (pinned to 433685b202)