{"record":{"id":"e21b6222c623b353","repo":"mastra-ai/mastra","slug":"async-buffering-is-not-yet-supported-with-scope","errorCode":null,"errorMessage":"Async buffering is not yet supported with scope: 'resource'. Use scope: 'thread', or set observation: { bufferTokens: false } to disable async buffering.","messagePattern":"Async buffering is not yet supported with scope: 'resource'\\. Use scope: 'thread', or set observation: (.+?) to disable async buffering\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/observational-memory.ts","lineNumber":976,"sourceCode":"   */\n  emitDebugEvent(event: ObservationDebugEvent): void {\n    if (this.onDebugEvent) {\n      this.onDebugEvent(event);\n    }\n  }\n\n  /**\n   * Validate buffer configuration on first use.\n   * Ensures bufferTokens is less than the threshold and bufferActivation is valid.\n   */\n  private validateBufferConfig(): void {\n    // Async buffering is not yet supported with resource scope\n    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","sourceCodeStart":958,"sourceCodeEnd":994,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/observational-memory.ts#L958-L994","documentation":"ObservationalMemory constructor rejects combining async token buffering (bufferTokens or bufferActivation set) with scope: 'resource', because buffering accumulates per-thread state that has no meaningful meaning when observations are shared at the resource level. The feature is simply not implemented for resource scope yet, so the constructor fails fast with guidance on alternatives.","triggerScenarios":"new ObservationalMemory({ scope: 'resource', observation: { bufferTokens: N } }) or observation: { bufferActivation: x } or reflection: { bufferActivation: x }, i.e. any async-buffering option set while scope is 'resource'.","commonSituations":"Copying a thread-scoped ObservationalMemory config and switching scope to 'resource' for cross-thread memory without removing buffer options; enabling async buffering to reduce latency on a resource-scoped processor.","solutions":["Change scope to 'thread' if per-thread buffering fits your use case.","Set observation: { bufferTokens: false } to explicitly disable async buffering while keeping resource scope.","Remove bufferTokens/bufferActivation options from both observation and reflection configs.","Track upstream releases for resource-scope buffering support before re-enabling."],"exampleFix":"// before\nconst memory = new ObservationalMemory({ scope: 'resource', observation: { bufferTokens: 2000 } });\n// after\nconst memory = new ObservationalMemory({ scope: 'resource', observation: { bufferTokens: false } });","handlingStrategy":"validation","validationCode":"const cfg = { scope: 'resource', observation: { bufferTokens: 2000 } } as const;\nconst hasAsyncBuffering = cfg.observation.bufferTokens !== undefined || cfg.observation.bufferActivation !== undefined;\nif (cfg.scope === 'resource' && hasAsyncBuffering) {\n  throw new Error('Async buffering is incompatible with resource scope');\n}","typeGuard":null,"tryCatchPattern":"try {\n  memory = new ObservationalMemory(userConfig);\n} catch (e) {\n  if (e.message.includes(\"scope: 'resource'\")) {\n    memory = new ObservationalMemory({ ...userConfig, observation: { ...userConfig.observation, bufferTokens: false } });\n  } else throw e;\n}","preventionTips":["When switching scope between 'thread' and 'resource', audit all buffer* options.","Keep a single shared config factory per scope type.","Add unit tests asserting construction succeeds for each shipped config."],"tags":["configuration","observational-memory","unsupported-feature"],"backgroundTag":"incompatible-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}