observation.bufferTokens must be > 0, got ${this.observation

Error message

observation.bufferTokens must be > 0, got ${this.observationConfig.bufferTokens}

What it means

The constructor validates that observation.bufferTokens, when provided, is a positive number. A value of 0 or negative would mean the buffer never accumulates anything or is inverted, which is nonsensical, so construction fails immediately with the offending value in the message.

Source

Thrown at packages/memory/src/processors/observational-memory/observational-memory.ts:986

   */
  private validateBufferConfig(): void {
    // Async buffering is not yet supported with resource scope
    const hasAsyncBuffering =
      this.observationConfig.bufferTokens !== undefined ||
      this.observationConfig.bufferActivation !== undefined ||
      this.reflectionConfig.bufferActivation !== undefined;
    if (hasAsyncBuffering && this.scope === 'resource') {
      throw new Error(
        `Async buffering is not yet supported with scope: 'resource'. ` +
          `Use scope: 'thread', or set observation: { bufferTokens: false } to disable async buffering.`,
      );
    }

    // Validate observation bufferTokens
    const observationThreshold = getMaxThreshold(this.observationConfig.messageTokens);
    if (this.observationConfig.bufferTokens !== undefined) {
      if (this.observationConfig.bufferTokens <= 0) {
        throw new Error(`observation.bufferTokens must be > 0, got ${this.observationConfig.bufferTokens}`);
      }
      if (this.observationConfig.bufferTokens >= observationThreshold) {
        throw new Error(
          `observation.bufferTokens (${this.observationConfig.bufferTokens}) must be less than messageTokens (${observationThreshold})`,
        );
      }
    }

    // Validate observation bufferActivation: (0, 1] for ratio, or >= 1000 for absolute retention tokens
    if (this.observationConfig.bufferActivation !== undefined) {
      if (this.observationConfig.bufferActivation <= 0) {
        throw new Error(`observation.bufferActivation must be > 0, got ${this.observationConfig.bufferActivation}`);
      }
      if (this.observationConfig.bufferActivation > 1 && this.observationConfig.bufferActivation < 1000) {
        throw new Error(
          `observation.bufferActivation must be <= 1 (ratio) or >= 1000 (absolute token retention), got ${this.observationConfig.bufferActivation}`,
        );
      }

View on GitHub (pinned to 75dd419e61)

Solutions

Set bufferTokens to a positive integer smaller than your messageTokens threshold (e.g. 1000-4000).
Remove the bufferTokens option entirely to use the default buffering behavior.
If the value comes from config/env, clamp it: Math.max(1, parsedValue).

Example fix

// before
new ObservationalMemory({ observation: { bufferTokens: Number(process.env.BUFFER_TOKENS) } });
// after
const bt = Number(process.env.BUFFER_TOKENS);
new ObservationalMemory({ observation: { bufferTokens: Number.isFinite(bt) && bt > 0 ? bt : undefined } });

Defensive patterns

Strategy: validation

Validate before calling

const bt = Number(process.env.OBS_BUFFER_TOKENS);
if (bt !== undefined && (!Number.isFinite(bt) || bt <= 0)) {
  throw new Error(`observation.bufferTokens must be > 0, got ${bt}`);
}

Type guard

function isValidBufferTokens(v: unknown): v is number {
  return typeof v === 'number' && Number.isFinite(v) && v > 0;
}

Try / catch

try {
  memory = new ObservationalMemory({ observation: { bufferTokens } });
} catch (e) {
  if (/bufferTokens must be > 0/.test(e.message)) {
    memory = new ObservationalMemory({}); // fall back to defaults
  } else throw e;
}

Prevention

Never feed raw env vars into bufferTokens; parse and clamp first.
Document bufferTokens as a positive integer in your config schema.
Test config construction at startup so failures surface before traffic.

When it happens

Trigger: new ObservationalMemory({ observation: { bufferTokens: 0 } }) or any value <= 0 (e.g. -500), typically from computed values like bufferTokens: someLimit - someLimit.

Common situations: Deriving bufferTokens from environment variables where the var is unset/0; arithmetic producing 0; typos passing milliseconds or percentages into a token field.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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