mastra-ai/mastra · error

observation.bufferActivation must be <= 1 (ratio) or >= 1000

Error message

observation.bufferActivation must be <= 1 (ratio) or >= 1000 (absolute token retention), got ${this.observationConfig.bufferActivation}

What it means

Same two-mode contract as the <= 0 check: bufferActivation must be either a ratio <= 1 (fraction of the threshold) or an absolute token count >= 1000. A value like 5 or 999 is rejected because the library cannot tell whether you meant a tiny ratio (nonsensical as 500%) or a too-small absolute retention, and refuses to guess.

Source

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

    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
      ) {
        throw new Error(
          `observation.bufferActivation as absolute retention (${this.observationConfig.bufferActivation}) must be less than messageTokens (${observationThreshold})`,
        );
      }
    }

    // Validate observation blockAfter
    if (this.observationConfig.blockAfter !== undefined) {
      if (this.observationConfig.blockAfter < observationThreshold) {
        throw new Error(
          `observation.blockAfter (${this.observationConfig.blockAfter}) must be >= messageTokens (${observationThreshold})`,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Convert percentage-style values to decimals: 150% becomes 1.5? No — ratios are capped at 1; use an absolute value >= 1000 instead.
2. If you need activation beyond the whole threshold, use absolute mode: bufferActivation >= 1000.
3. Keep ratio mode within (0, 1]: e.g. 0.25, 0.5, 1.

Example fix

// before
new ObservationalMemory({ observation: { bufferActivation: 999 } });
// after
new ObservationalMemory({ observation: { bufferActivation: 1000 } }); // absolute mode

const ba = observationConfig.bufferActivation;
if (ba !== undefined && ba > 1 && ba < 1000) {
  throw new Error(`bufferActivation ${ba} falls in the dead zone; use a ratio (0,1] or absolute >= 1000`);
}

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

When it happens

Trigger: new ObservationalMemory({ observation: { bufferActivation: 100 } }) or any value in (1, 1000): e.g. 1.5, 999.

Common situations: Writing 1.5 intending '150%' activation; passing token counts under 1000 assuming any positive integer is an absolute count; migrating configs from older versions with different validation rules.

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

• observationalMemory.experimental_subconscious must be a Subc
• `retrieval: { vector: true }` requires a vector store. Pass
• `retrieval: { vector: true }` requires an embedder. Pass an
• observation.bufferTokens must be > 0, got ${this.observation
• observation.bufferTokens (${this.observationConfig.bufferTok

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