{"record":{"id":"45620b96240866ec","repo":"mastra-ai/mastra","slug":"observation-buffertokens-this-observationconfig","errorCode":null,"errorMessage":"observation.bufferTokens (${this.observationConfig.bufferTokens}) must be less than messageTokens (${observationThreshold})","messagePattern":"observation\\.bufferTokens \\((.+?)\\) must be less than messageTokens \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/observational-memory.ts","lineNumber":989,"sourceCode":"    const hasAsyncBuffering =\n      this.observationConfig.bufferTokens !== undefined ||\n      this.observationConfig.bufferActivation !== undefined ||\n      this.reflectionConfig.bufferActivation !== undefined;\n    if (hasAsyncBuffering && this.scope === 'resource') {\n      throw new Error(\n        `Async buffering is not yet supported with scope: 'resource'. ` +\n          `Use scope: 'thread', or set observation: { bufferTokens: false } to disable async buffering.`,\n      );\n    }\n\n    // Validate observation bufferTokens\n    const observationThreshold = getMaxThreshold(this.observationConfig.messageTokens);\n    if (this.observationConfig.bufferTokens !== undefined) {\n      if (this.observationConfig.bufferTokens <= 0) {\n        throw new Error(`observation.bufferTokens must be > 0, got ${this.observationConfig.bufferTokens}`);\n      }\n      if (this.observationConfig.bufferTokens >= observationThreshold) {\n        throw new Error(\n          `observation.bufferTokens (${this.observationConfig.bufferTokens}) must be less than messageTokens (${observationThreshold})`,\n        );\n      }\n    }\n\n    // Validate observation bufferActivation: (0, 1] for ratio, or >= 1000 for absolute retention tokens\n    if (this.observationConfig.bufferActivation !== undefined) {\n      if (this.observationConfig.bufferActivation <= 0) {\n        throw new Error(`observation.bufferActivation must be > 0, got ${this.observationConfig.bufferActivation}`);\n      }\n      if (this.observationConfig.bufferActivation > 1 && this.observationConfig.bufferActivation < 1000) {\n        throw new Error(\n          `observation.bufferActivation must be <= 1 (ratio) or >= 1000 (absolute token retention), got ${this.observationConfig.bufferActivation}`,\n        );\n      }\n      if (\n        this.observationConfig.bufferActivation >= 1000 &&\n        this.observationConfig.bufferActivation >= observationThreshold","sourceCodeStart":971,"sourceCodeEnd":1007,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/observational-memory.ts#L971-L1007","documentation":"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.","triggerScenarios":"new ObservationalMemory({ observation: { messageTokens: 2000, bufferTokens: 2000 } }) or bufferTokens > messageTokens threshold, e.g. bufferTokens: 5000 with default messageTokens.","commonSituations":"Tuning bufferTokens upward for fewer reflection calls and accidentally exceeding messageTokens; copying a bufferTokens value from another project with a larger messageTokens setting.","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."],"exampleFix":"// before\nnew ObservationalMemory({ observation: { messageTokens: 2000, bufferTokens: 2500 } });\n// after\nnew ObservationalMemory({ observation: { messageTokens: 2000, bufferTokens: 1000 } });","handlingStrategy":"validation","validationCode":"const observationThreshold = getMaxThreshold(observationConfig.messageTokens);\nif (observationConfig.bufferTokens !== undefined && observationConfig.bufferTokens >= observationThreshold) {\n  throw new Error(`bufferTokens (${observationConfig.bufferTokens}) must be < messageTokens (${observationThreshold})`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["configuration","validation","observational-memory","token-limits"],"backgroundTag":"invalid-config-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}