{"record":{"id":"53f8db245db267a1","repo":"mastra-ai/mastra","slug":"observation-bufferactivation-must-be-1-ratio","errorCode":null,"errorMessage":"observation.bufferActivation must be <= 1 (ratio) or >= 1000 (absolute token retention), got ${this.observationConfig.bufferActivation}","messagePattern":"observation\\.bufferActivation must be <= 1 \\(ratio\\) or >= 1000 \\(absolute token retention\\), got (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/observational-memory.ts","lineNumber":1001,"sourceCode":"    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\n      ) {\n        throw new Error(\n          `observation.bufferActivation as absolute retention (${this.observationConfig.bufferActivation}) must be less than messageTokens (${observationThreshold})`,\n        );\n      }\n    }\n\n    // Validate observation blockAfter\n    if (this.observationConfig.blockAfter !== undefined) {\n      if (this.observationConfig.blockAfter < observationThreshold) {\n        throw new Error(\n          `observation.blockAfter (${this.observationConfig.blockAfter}) must be >= messageTokens (${observationThreshold})`,","sourceCodeStart":983,"sourceCodeEnd":1019,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/observational-memory.ts#L983-L1019","documentation":"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.","triggerScenarios":"new ObservationalMemory({ observation: { bufferActivation: 100 } }) or any value in (1, 1000): e.g. 1.5, 999.","commonSituations":"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.","solutions":["Convert percentage-style values to decimals: 150% becomes 1.5? No — ratios are capped at 1; use an absolute value >= 1000 instead.","If you need activation beyond the whole threshold, use absolute mode: bufferActivation >= 1000.","Keep ratio mode within (0, 1]: e.g. 0.25, 0.5, 1."],"exampleFix":"// before\nnew ObservationalMemory({ observation: { bufferActivation: 999 } });\n// after\nnew ObservationalMemory({ observation: { bufferActivation: 1000 } }); // absolute mode","handlingStrategy":"validation","validationCode":"const ba = observationConfig.bufferActivation;\nif (ba !== undefined && ba > 1 && ba < 1000) {\n  throw new Error(`bufferActivation ${ba} falls in the dead zone; use a ratio (0,1] or absolute >= 1000`);\n}","typeGuard":"function isAbsoluteBufferActivation(v: unknown): v is number {\n  return typeof v === 'number' && Number.isFinite(v) && v >= 1000;\n}","tryCatchPattern":null,"preventionTips":["Pick one mode per codebase (ratio or absolute) and lint against the other.","Remember ratios cap at 1; anything above means you wanted absolute mode.","Write config round-trip tests covering boundary values 1 and 1000."],"tags":["configuration","validation","observational-memory"],"backgroundTag":"invalid-config-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}