{"record":{"id":"419bfe0a15ca38cd","repo":"oven-sh/bun","slug":"workload-name-wrote-an-invalid-trace","errorCode":null,"errorMessage":"workload \"${name}\" wrote an invalid trace","messagePattern":"workload \"(.+?)\" wrote an invalid trace","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/orderfile/generate.ts","lineNumber":172,"sourceCode":"}\n\n/** Write function starts for functrace.c: u64 magic, version, count, addresses. */\nfunction writeStarts(path: string, addresses: number[]): void {\n  const buffer = new ArrayBuffer((STARTS_HEADER_WORDS + addresses.length) * 8);\n  const words = new BigUint64Array(buffer);\n  words[0] = STARTS_MAGIC;\n  words[1] = 1n;\n  words[2] = BigInt(addresses.length);\n  for (let i = 0; i < addresses.length; i++) words[STARTS_HEADER_WORDS + i] = BigInt(addresses[i]!);\n  writeFileSync(path, new Uint8Array(buffer));\n}\n\n/** Read a trace functrace.c wrote: first-entry addresses, slide already removed. */\nfunction readTrace(path: string, name: string): number[] {\n  const raw = readFileSync(path);\n  if (raw.byteLength < TRACE_HEADER_WORDS * 8) throw new Error(`workload \"${name}\" wrote a truncated trace`);\n  const header = new BigUint64Array(raw.buffer, raw.byteOffset, TRACE_HEADER_WORDS);\n  if (header[0] !== TRACE_MAGIC || header[1] !== 1n) throw new Error(`workload \"${name}\" wrote an invalid trace`);\n  const count = Number(header[4]);\n  if (count === 0) throw new Error(`workload \"${name}\" recorded no entries — is the tracer loading?`);\n  const body = new BigUint64Array(raw.buffer, raw.byteOffset + TRACE_HEADER_WORDS * 8, count);\n  const out: number[] = new Array(count);\n  for (let i = 0; i < count; i++) out[i] = Number(body[i]);\n  return out;\n}\n\nexport function generateOrderFile(options: GenerateOptions): { count: number; outPath: string } {\n  const buildDir = resolve(options.buildDir);\n  const outPath = resolve(options.outPath ?? join(buildDir, \"linker.order\"));\n  const minFunctions = options.minFunctions ?? MIN_FUNCTIONS;\n  const log = (message: string) => options.verbose && console.log(message);\n\n  const darwin = process.platform === \"darwin\";\n  if (process.platform !== \"linux\" && !(darwin && process.arch === \"arm64\")) {\n    throw new Error(\"the order file tracer builds on linux x86-64/arm64 or macOS arm64\");\n  }","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/oven-sh/bun/blob/8c5296ac459e8252d3cd702f3fbcbb0c249d95d5/scripts/orderfile/generate.ts#L154-L190","documentation":"The trace file is large enough but its header magic/version words do not equal TRACE_MAGIC/1, so the file was not written by the current tracer. This guards against consuming stale or foreign data before trusting the address list.","triggerScenarios":"A stale file already exists at the BUN_FUNCTRACE_OUT path from an earlier tracer revision; two tracer versions sharing an out path; a garbage/hand-made file left where the workload expects to write.","commonSituations":"Re-running generate with a reused out directory after functrace.c's format changed; concurrent runs writing to the same fixed path.","solutions":["Delete stale trace files / clear the output directory before re-running","Ensure each run uses a unique scratch out path (the generator already mkdtemp's its scratch)","Rebuild the tracer from the current functrace.c so writer and reader agree on the format"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import { existsSync, unlinkSync } from \"node:fs\";\n\n// A pre-existing out file may carry an older format — remove it so only the current tracer writes it.\nif (existsSync(outPath)) unlinkSync(outPath);","typeGuard":null,"tryCatchPattern":"try {\n  processTrace(out);\n} catch (err) {\n  if (/invalid trace/.test(String(err))) {\n    unlinkSync(out); // discard stale-format file\n    return retryWorkload();\n  }\n  throw err;\n}","preventionTips":["Always write traces into a fresh mkdtemp scratch dir (as generate.ts does) instead of a fixed reused path","Bump the trace version constant whenever functrace.c's layout changes so mismatches are detectable"],"tags":["tracing","orderfile","version-mismatch","stale-state"],"backgroundTag":null,"analyzedSha":"8c5296ac459e8252d3cd702f3fbcbb0c249d95d5","analyzedAt":"2026-08-16T08:01:58.794Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}