mastra-ai/mastra · error

Inspector session is unavailable.

Error message

Inspector session is unavailable.

What it means

startSampling throws this when this.inspector is null, i.e. the V8 inspector session has not been created or has been disconnected, so HeapProfiler.startSampling cannot be posted. It is an internal-state guard protecting the allocation-sampling setup path.

Source

Thrown at mastracode/sdk/src/process-memory-diagnostics.ts:522

          timestamp,
          sequence: this.gcEventCount,
          name: entry.name,
          startTime: entry.startTime,
          duration: entry.duration,
          kind: gcEntry.detail?.kind ?? gcEntry.kind ?? null,
          flags: gcEntry.detail?.flags ?? gcEntry.flags ?? null,
          before,
          after,
          latestSampleSequence: this.latestSample?.sequence ?? null,
        });
      }
    });
    observer.observe({ entryTypes: ['gc'] });
    this.observer = observer;
  }

  private async startSampling(): Promise<void> {
    if (!this.inspector) throw new Error('Inspector session is unavailable.');
    await this.inspector.post('HeapProfiler.startSampling', {
      samplingInterval: this.config.allocationIntervalBytes,
      includeObjectsCollectedByMajorGC: true,
      includeObjectsCollectedByMinorGC: true,
    });
    this.samplingActive = true;
  }

  private async takeSample(): Promise<ProcessMemoryDiagnosticsMemorySample> {
    if (!this.outputDirectory || !this.startedAt) throw new Error('Diagnostics output directory is unavailable.');
    const sample: ProcessMemoryDiagnosticsMemorySample = {
      timestamp: this.now().toISOString(),
      sequence: this.sampleCount + 1,
      elapsedMs: Math.max(0, this.now().getTime() - this.startedAt.getTime()),
      memory: process.memoryUsage(),
      resourceUsage: process.resourceUsage(),
      heap: getHeapStatistics(),
      heapSpaces: getHeapSpaceStatistics(),

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure start() completed (state 'active') before capturing; capture() already rejects when not active
2. Check for overlapping start/stop calls — stop() disconnects the inspector; await the stop promise before restarting
3. If injecting a custom createInspectorSession, verify it returns a connected-capable session and does not disconnect early

Example fix

// before
const setup = createProcessMemoryDiagnosticsFromEnvironment(env);
setup.diagnostics.capture(); // may race stop()
await stopProcessMemoryDiagnosticsWithTimeout(setup.diagnostics, warn);
setup.diagnostics.capture();
// after
const setup = createProcessMemoryDiagnosticsFromEnvironment(env);
await stopProcessMemoryDiagnosticsWithTimeout(setup.diagnostics, warn);
// no capture after stop; restart with start() first if needed

const status = diagnostics.getStatus();
if (status.state !== 'active') throw new Error(`Diagnostics not active (state=${status.state}); inspector may be disconnected`);

try {
  await startConfiguredProcessMemoryDiagnostics(setup, warn);
} catch (error) {
  if (error.message === 'Inspector session is unavailable.') {
    console.error('Inspector was disconnected (previous stop/failure). Create a new diagnostics instance.');
  } else throw error;
}

When it happens

Trigger: startSampling is invoked from startRun before/without a connected inspector, or from captureEpoch/restartSamplingAfterFailure after disconnectInspector() (post-stop or post-start-failure) set inspector to null.

Common situations: Concurrent start()/stop() races, a failed start whose cleanup ran while a queued capture still restarts sampling, or a custom createInspectorSession dependency returning null-like sessions that were disconnected.

Related errors

• Allocation sampling is not active.
• Allocation sampling did not restart.
• Diagnostics output directory is unavailable.
• ${this.latestError}

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/89c9472cdfc4a355. Report an issue: GitHub.