{"record":{"id":"08f2216cebb55274","repo":"mastra-ai/mastra","slug":"gc-event-buffer-exceeded-max-pending-gc-events","errorCode":null,"errorMessage":"GC event buffer exceeded ${MAX_PENDING_GC_EVENTS} records before the next process sample.","messagePattern":"GC event buffer exceeded (.+?) records before the next process sample\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"mastracode/sdk/src/process-memory-diagnostics.ts","lineNumber":441,"sourceCode":"    this.stopRequested = true;\n    this.state = 'stopping';\n    this.clearTimersAndObserver();\n\n    if (startingPromise) {\n      this.stoppingPromise = startingPromise.then(() => this.getStatus());\n      return this.stoppingPromise;\n    }\n\n    this.stoppingPromise = (async () => {\n      let stopError: string | null = null;\n      try {\n        if (this.outputDirectory) await this.takeSample();\n        await this.enqueueCapture(async () => {\n          if (this.inspector && this.samplingActive) await this.captureEpoch('stop', true);\n        });\n        await this.writeQueue;\n        if (this.gcEventBufferOverflowed) {\n          throw new Error(`GC event buffer exceeded ${MAX_PENDING_GC_EVENTS} records before the next process sample.`);\n        }\n        if (this.artifactWriteFailed) throw new Error('One or more process memory diagnostic artifact writes failed.');\n        this.latestError = null;\n      } catch (error) {\n        stopError = `Unable to stop process memory diagnostics cleanly: ${errorMessage(error)}`;\n        this.latestError = stopError;\n      } finally {\n        this.disconnectInspector();\n        this.state = stopError ? 'error' : 'inactive';\n      }\n      return this.getStatus();\n    })();\n\n    return this.stoppingPromise;\n  }\n\n  private async createArtifacts(): Promise<void> {\n    await mkdir(this.config.parentDirectory, { recursive: true, mode: 0o700 });","sourceCodeStart":423,"sourceCodeEnd":459,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/process-memory-diagnostics.ts#L423-L459","documentation":"Thrown during stop() when the in-memory pending GC event buffer overflowed (more than MAX_PENDING_GC_EVENTS=1000 events accumulated between process samples), meaning GC events were dropped and the gc-events.jsonl artifact is incomplete. stop() refuses to report a clean stop so the operator knows the GC log has gaps.","triggerScenarios":"Calling stop() when gcEventBufferOverflowed is true — i.e. the PerformanceObserver 'gc' callback filled pendingGcEvents to the 1000 cap before the periodic sample timer flushed them. Happens when sampling fails/stalls or the sample interval is long while the workload triggers very frequent GC.","commonSituations":"GC-heavy workloads (huge short-lived allocations) combined with a long MASTRACODE_PROFILE_SAMPLE_INTERVAL_MS, or timers not firing because the sample write queue is blocked.","solutions":["Lower MASTRACODE_PROFILE_SAMPLE_INTERVAL_MS (closer to the 1000ms minimum) so pending GC events flush more often","Increase heap headroom / reduce allocation churn so fewer GC events occur per interval","Treat the run's gc-events.jsonl as partial; re-run the profiling session with a shorter sample interval"],"exampleFix":"// before\nMASTRACODE_PROFILE_SAMPLE_INTERVAL_MS=600000\n// after\nMASTRACODE_PROFILE_SAMPLE_INTERVAL_MS=10000","handlingStrategy":"try-catch","validationCode":"const status = diagnostics.getStatus();\nif (status.gcEventCount > 900) console.warn('GC event count approaching buffer cap; consider shorter sample interval');","typeGuard":null,"tryCatchPattern":"try {\n  await diagnostics.stop();\n} catch (error) {\n  if (error.message.includes('GC event buffer exceeded')) {\n    console.warn('GC events dropped; gc-events.jsonl is partial. Re-run with shorter sample interval.');\n  } else throw error;\n}","preventionTips":["Keep MASTRACODE_PROFILE_SAMPLE_INTERVAL_MS well below the cap-flush horizon (default 10000ms)","Avoid extreme allocation churn while profiling; large arrays of short-lived objects generate thousands of GC events","Check getStatus().gcEventCount periodically during long runs","Note createProcessMemoryDiagnosticsFromEnvironment tolerates config errors, but this one surfaces via stop; read the stop status"],"tags":["gc","buffer-overflow","diagnostics"],"backgroundTag":"gc-event-buffer-overflow","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}