observation.bufferTokens (${this.observationConfig.bufferTok

Error message

observation.bufferTokens (${this.observationConfig.bufferTokens}) must be less than messageTokens (${observationThreshold})

What it means

observation.bufferTokens must be strictly less than the effective messageTokens threshold (the max threshold derived from observationConfig.messageTokens). If the buffer is allowed to grow as large as the flush threshold, the buffer would trigger at the same point as a full message batch, defeating the purpose of incremental buffering — so the constructor rejects it.

Source

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

    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}`,
        );
      }
      if (
        this.observationConfig.bufferActivation >= 1000 &&
        this.observationConfig.bufferActivation >= observationThreshold

View on GitHub (pinned to 75dd419e61)

Solutions

Lower bufferTokens below the messageTokens threshold (e.g. bufferTokens = messageTokens / 2).
Raise observation.messageTokens if you genuinely want a bigger buffer, keeping bufferTokens strictly less.
Remove bufferTokens to let the library derive a sensible default from messageTokens.

Example fix

// before
new ObservationalMemory({ observation: { messageTokens: 2000, bufferTokens: 2500 } });
// after
new ObservationalMemory({ observation: { messageTokens: 2000, bufferTokens: 1000 } });

Defensive patterns

Strategy: validation

Validate before calling

const observationThreshold = getMaxThreshold(observationConfig.messageTokens);
if (observationConfig.bufferTokens !== undefined && observationConfig.bufferTokens >= observationThreshold) {
  throw new Error(`bufferTokens (${observationConfig.bufferTokens}) must be < messageTokens (${observationThreshold})`);
}

Prevention

Derive bufferTokens from messageTokens (e.g. half) instead of hardcoding both independently.
Keep a single source of truth for token limits in config.
Assert the invariant bufferTokens < messageTokens in config tests.

When it happens

Trigger: new ObservationalMemory({ observation: { messageTokens: 2000, bufferTokens: 2000 } }) or bufferTokens > messageTokens threshold, e.g. bufferTokens: 5000 with default messageTokens.

Common situations: Tuning bufferTokens upward for fewer reflection calls and accidentally exceeding messageTokens; copying a bufferTokens value from another project with a larger messageTokens setting.

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/45620b96240866ec. Report an issue: GitHub.