mastra-ai/mastra · error

reflection.blockAfter requires reflection.bufferActivation t

Error message

reflection.blockAfter requires reflection.bufferActivation to be set (blockAfter only applies when async reflection is enabled)

What it means

`reflection.blockAfter` only has effect when async reflection is enabled via `reflection.bufferActivation`. If `blockAfter` is set but `bufferActivation` is falsy (undefined/0), the config is contradictory — blocking would never trigger. ObservationalMemory throws at construction to surface this dependency instead of silently ignoring blockAfter.

Source

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

    // Validate reflection bufferActivation (0-1 float range)
    if (this.reflectionConfig.bufferActivation !== undefined) {
      if (this.reflectionConfig.bufferActivation <= 0 || this.reflectionConfig.bufferActivation > 1) {
        throw new Error(
          `reflection.bufferActivation must be in range (0, 1], got ${this.reflectionConfig.bufferActivation}`,
        );
      }
    }

    // Validate reflection blockAfter
    if (this.reflectionConfig.blockAfter !== undefined) {
      const reflectionThreshold = getMaxThreshold(this.reflectionConfig.observationTokens);
      if (this.reflectionConfig.blockAfter < reflectionThreshold) {
        throw new Error(
          `reflection.blockAfter (${this.reflectionConfig.blockAfter}) must be >= reflection.observationTokens (${reflectionThreshold})`,
        );
      }
      if (!this.reflectionConfig.bufferActivation) {
        throw new Error(
          `reflection.blockAfter requires reflection.bufferActivation to be set (blockAfter only applies when async reflection is enabled)`,
        );
      }
    }
  }

  /**
   * Resolve the effective messageTokens for a record.
   * Only explicit per-record overrides (stored under `_overrides`) win;
   * the initial config snapshot written by getOrCreateRecord() is ignored
   * so that later instance-level changes still take effect.
   *
   * Overrides that fall below the instance-level buffering floor
   * (bufferTokens / absolute bufferActivation) are clamped to the
   * instance threshold to preserve buffering invariants.
   */
  private getEffectiveMessageTokens(record: ObservationalMemoryRecord): number | ThresholdRange {
    const overrides = (record.config as { _overrides?: { observation?: { messageTokens?: number | ThresholdRange } } })

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add a valid `bufferActivation` value in (0, 1] alongside `blockAfter`.
2. Remove `blockAfter` if you do not intend to use async reflection.
3. If bufferActivation comes from external config, ensure it is present whenever blockAfter is present (validate together).

Example fix

// before
reflection: { blockAfter: 5000 }
// after
reflection: { bufferActivation: 0.3, blockAfter: 5000 }

const r = config.reflection ?? {};
if (r.blockAfter !== undefined && !r.bufferActivation) {
  throw new Error('reflection.blockAfter requires reflection.bufferActivation');
}

When it happens

Trigger: Constructing ObservationalMemory with `reflection: { blockAfter: 5000 }` but no `bufferActivation`, or with `bufferActivation: 0`, inside the blockAfter validation block (observational-memory.ts:1062).

Common situations: Following docs/snippets that show only blockAfter; partially migrating config where bufferActivation was removed in a refactor; assuming blockAfter enables async reflection implicitly.

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