Hmbown/CodeWhale · error · Error

Import exceeds the event limit.

Error message

Import exceeds the ${maxEvents.toLocaleString()} event limit.

What it means

During fromCodewhaleSession() entry conversion, each source entry emits one or more events; once the events array reaches maxEvents the import aborts with this error rather than silently truncating the session trace. The limit protects the analyzer from unbounded memory use on very large sessions.

Solutions

  1. Increase the maxEvents option passed to trace()/fromCodewhaleSession for large sessions (mind memory cost).
  2. Split or truncate the session export so each import stays within the limit.
  3. Pre-filter journal entries (e.g. drop delta-heavy items) before import to reduce emitted event count.
  4. Check whether a caller is passing an accidentally small maxEvents (e.g. 0 or a test value).

Example fix

// before
const trace = trace(bigSession); // default maxEvents
// after
const trace = trace(bigSession, { maxEvents: 1_000_000 });
Defensive patterns

Strategy: try-catch

Validate before calling

// rough pre-check: entries fan out to >=1 event each
if (sourceEntries.length * 4 > maxEvents) console.warn(`${file} may exceed maxEvents=${maxEvents}`);

Try / catch

try { trace = fromCodewhaleSession(doc, file, { maxEvents }); }
catch (e) {
  const m = e.message.match(/exceeds the ([\d,]+) event limit/);
  if (m) { maxEvents = parseInt(m[1].replace(/,/g, ''), 10) * 2; return retry(); }
  throw e;
}

Prevention

When it happens

Trigger: Importing a session document whose journal/messages expand to more than maxEvents trace events — e.g. a long-running session with thousands of tool calls, message blocks, and deltas, or calling trace() with a lowered maxEvents option on a moderately large session.

Common situations: Analyzing a multi-day session export, batching many sessions through one importer configured with a small cap, or a version change where entries now fan out into more events per journal entry.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at pet/src/core/codewhale.ts:184

  }

  const events: WhaleEvent[] = [];
  const pending = new Map<string, number>();
  let seq = 0;
  const originWall = orderOnly ? undefined : sourceEntries.map(e => parseTime(e.created_at)).find((n): n is number => n !== undefined);
  const agentId = 'parent';
  const model = str(metadata.model);
  const provider = str(metadata.model_provider);

  const when = (entry: Obj, fallback: number): { start: number; open: boolean } => {
    if (orderOnly || originWall === undefined) return { start: fallback, open: false };
    const t = parseTime(entry.created_at);
    if (t === undefined) return { start: fallback, open: true };
    return { start: t - originWall, open: false };
  };

  for (const entry of sourceEntries) {
    if (events.length >= maxEvents) throw new Error(`Import exceeds the ${maxEvents.toLocaleString()} event limit.`);
    const entryId = str(entry.id) ?? `${sessionId}/entry/${seq}`;
    const message = obj(entry.message ?? (entry.kind === 'message' ? entry : {}));
    const role = str(message.role) ?? (str(entry.kind) === 'user' ? 'user' : str(entry.kind) === 'assistant' ? 'assistant' : undefined);
    const blocks: Obj[] = Array.isArray(message.content) ? message.content.map(obj) : [];
    if (!blocks.length) {
      const text = str(entry.text) ?? str(message.text);
      if (text) blocks.push({ type: role === 'user' ? 'text' : 'text', text });
    }
    if (!blocks.length) continue;
    const parentEventId = events.length ? events[events.length - 1]!.id : undefined;
    for (const block of blocks) {
      const t = when(entry, seq);
      const idBase = `${entryId}/${seq}`;
      const type = str(block.type) ?? 'text';
      const raw = pointer('codewhale.session/v1', { sessionId, entryId, seq, blockType: type, toolUseId: block.id ?? block.tool_use_id });
      if (type === 'tool_use' || type === 'server_tool_use') {
        const tool = str(block.name) ?? 'tool';
        const callId = str(block.id) ?? idBase;

View on GitHub (pinned to 433685b202)