{"record":{"id":"4b2165422aeddd4e","repo":"mastra-ai/mastra","slug":"runscope-missing-required-slot-sym-tostring","errorCode":null,"errorMessage":"RunScope: missing required slot ${sym.toString()}","messagePattern":"RunScope: missing required slot (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/mastra/run-scope.ts","lineNumber":66,"sourceCode":"  getOrThrow<T>(key: RunScopeKey<T>): T;\n  set<T>(key: RunScopeKey<T>, value: T): void;\n  delete<T>(key: RunScopeKey<T>): void;\n  has<T>(key: RunScopeKey<T>): boolean;\n  /** Test-only: number of slots currently populated. */\n  readonly size: number;\n}\n\nclass MapRunScope implements RunScope {\n  readonly #slots = new Map<symbol, unknown>();\n\n  get<T>(key: RunScopeKey<T>): T | undefined {\n    return this.#slots.get(key as unknown as symbol) as T | undefined;\n  }\n\n  getOrThrow<T>(key: RunScopeKey<T>): T {\n    const sym = key as unknown as symbol;\n    if (!this.#slots.has(sym)) {\n      throw new Error(`RunScope: missing required slot ${sym.toString()}`);\n    }\n    return this.#slots.get(sym) as T;\n  }\n\n  set<T>(key: RunScopeKey<T>, value: T): void {\n    this.#slots.set(key as unknown as symbol, value);\n  }\n\n  delete<T>(key: RunScopeKey<T>): void {\n    this.#slots.delete(key as unknown as symbol);\n  }\n\n  has<T>(key: RunScopeKey<T>): boolean {\n    return this.#slots.has(key as unknown as symbol);\n  }\n\n  get size(): number {\n    return this.#slots.size;","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/mastra/run-scope.ts#L48-L84","documentation":"RunScope stores values under symbol keys; getOrThrow<T>(key) requires the slot to have been set and throws a plain Error naming the missing symbol if it was never populated. It is used to guarantee that messageList, stored, and loopOptions are present before dependent code runs — a slot may be read only after some upstream code called set().","triggerScenarios":"Calling scope.getOrThrow(RunScopeKeys.messageList) (or stored/loopOptions) on a RunScope where that slot was never set — e.g. reading before the scope was populated, or using a scope instance created independently from the one being filled.","commonSituations":"Custom agent-loop or storage code reading a scope slot before the framework populates it; mixing up two RunScope instances (fresh one vs. the populated one); accidentally clearing/creating the scope mid-request so symbols from another scope are queried.","solutions":["Use the optional get(key) accessor when the slot may legitimately be absent, and handle undefined.","Ensure the code that sets the slot (scope.set(key, value)) runs before any getOrThrow on that key, in the same request/scope instance.","Pass the same RunScope instance through the call chain instead of constructing a new one.","Wrap getOrThrow in try/catch if absence is expected in some code paths, and fall back to constructing the value."],"exampleFix":"// before\nconst list = scope.getOrThrow(RunScopeKeys.messageList); // may throw if unset\n// after\nconst list = scope.get(RunScopeKeys.messageList);\nif (!list) throw new Error('messageList not yet initialized'); // or initialize it before this point","handlingStrategy":"fallback","validationCode":"if (!scope.has?.(RunScopeKeys.messageList)) {\n  throw new Error('messageList slot must be set before reading it from RunScope');\n}","typeGuard":null,"tryCatchPattern":"let messageList;\ntry {\n  messageList = scope.getOrThrow(RunScopeKeys.messageList);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('RunScope: missing required slot')) {\n    messageList = createFallbackMessageList(); // or propagate a clearer error\n  } else throw e;\n}","preventionTips":["Always use getOrThrow for slots guaranteed by the framework, and plain get() for optional ones.","Populate all required slots immediately after RunScope creation, before any consumer runs.","Pass a single RunScope instance through the request; never re-create it mid-request."],"tags":["run-scope","missing-slot","initialization-order"],"backgroundTag":"missing-required-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}