{"record":{"id":"f954e48b05aea3eb","repo":"mastra-ai/mastra","slug":"diagnostics-output-directory-is-unavailable","errorCode":null,"errorMessage":"Diagnostics output directory is unavailable.","messagePattern":"Diagnostics output directory is unavailable\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/process-memory-diagnostics.ts","lineNumber":532,"sourceCode":"        });\n      }\n    });\n    observer.observe({ entryTypes: ['gc'] });\n    this.observer = observer;\n  }\n\n  private async startSampling(): Promise<void> {\n    if (!this.inspector) throw new Error('Inspector session is unavailable.');\n    await this.inspector.post('HeapProfiler.startSampling', {\n      samplingInterval: this.config.allocationIntervalBytes,\n      includeObjectsCollectedByMajorGC: true,\n      includeObjectsCollectedByMinorGC: true,\n    });\n    this.samplingActive = true;\n  }\n\n  private async takeSample(): Promise<ProcessMemoryDiagnosticsMemorySample> {\n    if (!this.outputDirectory || !this.startedAt) throw new Error('Diagnostics output directory is unavailable.');\n    const sample: ProcessMemoryDiagnosticsMemorySample = {\n      timestamp: this.now().toISOString(),\n      sequence: this.sampleCount + 1,\n      elapsedMs: Math.max(0, this.now().getTime() - this.startedAt.getTime()),\n      memory: process.memoryUsage(),\n      resourceUsage: process.resourceUsage(),\n      heap: getHeapStatistics(),\n      heapSpaces: getHeapSpaceStatistics(),\n    };\n    this.sampleCount = sample.sequence;\n    this.latestSample = sample;\n    await this.enqueueWrite('process-samples.jsonl', sample);\n    const gcEvents = this.pendingGcEvents.splice(0);\n    if (gcEvents.length > 0) await this.enqueueWriteBatch('gc-events.jsonl', gcEvents);\n    return sample;\n  }\n\n  private enqueueWrite(fileName: string, value: unknown): Promise<void> {","sourceCodeStart":514,"sourceCodeEnd":550,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/process-memory-diagnostics.ts#L514-L550","documentation":"takeSample throws this when the output directory or start timestamp is missing, meaning sampling was invoked before createArtifacts() ran or after cleanup nulls outputDirectory. It guards the invariant that samples can only be written into an initialized run directory.","triggerScenarios":"stop() calls takeSample() when outputDirectory is null (start failed early or cleanup already ran), or a queued sample fires after cleanupAfterStartFailure removed the directory; also if startedAt was never set.","commonSituations":"Calling stop() while diagnostics are in 'error' state after a failed start, racing stop() against start(), or artifact cleanup removing the directory while an interval callback is mid-flight.","solutions":["Only call start()/stop() sequentially; await start() before stop() and avoid re-entrant calls on the same instance","Check diagnostics.getStatus().state — if 'error' or 'inactive' with null outputDirectory, do not expect samples; create a new ProcessMemoryDiagnostics","If start failed, fix the underlying artifact-creation error (parent directory permissions/disk) before retrying"],"exampleFix":"// before\nconst d = new ProcessMemoryDiagnostics(config);\nawait d.stop(); // stop-while-starting race on a failed start\n// after\nconst status = await d.start();\nif (status.state === 'active') await d.stop();","handlingStrategy":"validation","validationCode":"const status = diagnostics.getStatus();\nif (status.outputDirectory === null || status.state !== 'active') {\n  throw new Error('Diagnostics not initialized; call start() and await an active state before sampling.');\n}","typeGuard":"function isActiveWithOutput(\n  status: ProcessMemoryDiagnosticsStatus,\n): status is ProcessMemoryDiagnosticsStatus & { outputDirectory: string } {\n  return status.state === 'active' && status.outputDirectory !== null;\n}","tryCatchPattern":"try {\n  const sample = await diagnostics.start();\n} catch (error) {\n  if (error.message === 'Diagnostics output directory is unavailable.') {\n    console.error('Start failed or was torn down; fix artifact directory issues and retry start().');\n  } else throw error;\n}","preventionTips":["Always await start() and confirm status.state === 'active' before triggering work that samples","Fix underlying start failures (parent directory permissions, mkdir/chmod errors) — cleanup nulls outputDirectory after them","Avoid calling stop() concurrently with start(); await the starting promise first","Recreate the instance after a failed run rather than reusing one in 'error' state"],"tags":["state-error","diagnostics","initialization"],"backgroundTag":"output-directory-unavailable","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}