Hmbown/CodeWhale · error · Error

The trace file is empty.

Error message

The trace file is empty.

What it means

After stripping a BOM and trimming whitespace, importTrace requires non-empty input; an empty (or whitespace-only) file cannot yield a trace so it is rejected up front rather than producing zero traces silently.

Solutions

1. Check the file has content before importing (byte length > 0 after trimming whitespace/BOM).
2. Re-export the trace; an empty file usually means the original export failed.
3. Guard the call site: skip import when text.trim() is empty and show a friendlier message.

Example fix

// before
const traces = importTrace(text);
// after
if (!text.replace(/^\uFEFF/, '').trim()) throw new Error('Please select a non-empty trace file.');
const traces = importTrace(text);

const trimmed = text.replace(/^\uFEFF/, '').trim();
if (!trimmed) throw new Error('Trace file is empty; select a valid export.');

try {
  importTrace(text);
} catch (e) {
  if (e instanceof Error && e.message === 'The trace file is empty.') {
    console.error('The selected file has no content; re-export the trace.');
  }
}

When it happens

Trigger: Calling importTrace(''), importTrace(' \n'), or a file containing only a BOM (\uFEFF) — after trim() the text is empty and this throws.

Common situations: Export process crashed mid-write leaving a 0-byte file; reading a path that resolves to an empty placeholder; the UI passing an unset variable concatenated into an empty string.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• base URL cannot be empty
• browser URL cannot be empty
• classifier-approved read command was empty
• Codewhale runtime event file is empty.
• CRON field must not be empty

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

Appendix: source

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

      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) => {
      try { return JSON.parse(line); } catch { throw new Error(`Invalid JSON on nonempty line ${i + 1}. Import cancelled; no rows were skipped.`); }
    });
  }
  // Transform before both normalization and raw retention, so raw cannot bypass redaction.
  const safe = mode === 'retain' ? (options.redactor ? options.redactor(document, '') : document) : redact(document, '', options.redactor);
  const root = obj(safe);
  if(root.format === 'whalesong.evidence/v1') return [evidenceToTrace(validateBundle(root, Math.min(maxEvents, 100_000)))];
  if (isCodewhaleSession(safe)) {
    const trace = fromCodewhaleSession(safe, filename, maxEvents);
    trace.privacy = mode;
    trace.events = trace.events.map(e => privacyEvent(e, mode));
    return [trace];
  }
  const records = Array.isArray(safe) ? safe : Array.isArray(root.events) ? root.events : null;

View on GitHub (pinned to 433685b202)