{"record":{"id":"887e93cee7518d6a","repo":"mastra-ai/mastra","slug":"a-session-workspace-must-be-a-valid-workspace-inst","errorCode":null,"errorMessage":"A session workspace must be a valid Workspace instance.","messagePattern":"A session workspace must be a valid Workspace instance\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/agent-controller/session.ts","lineNumber":2905,"sourceCode":"    this.thread = new SessionThread(() => this.identity.getResourceId());\n    this.displayState = new SessionDisplayState({\n      getTokenUsage: () => this.getTokenUsage(),\n      getSubagentDisplayName: agentType => this.#resolveSubagentName?.(agentType),\n      getThreadId: () => this.thread.getId(),\n      clearFollowUps: () => this.followUps.clear(),\n    });\n    this.#bus.setDisplayState(this.displayState);\n    this.state = new SessionState(state ?? { initialState: {} as TState }, this.#bus, () => {\n      // Pin persistence to the thread active when the state update was\n      // requested — a queued preference update must not land in the metadata\n      // of a thread the session switched to in the meantime.\n      const threadId = this.thread.getId();\n      if (threadId === null) return undefined;\n      return args => this.thread.setSettingOn({ threadId, ...args });\n    });\n\n    if (workspace !== undefined && !(workspace instanceof Workspace)) {\n      throw new Error(`A session workspace must be a valid Workspace instance.`);\n    }\n\n    this.#workspace = workspace;\n    this.browser = browser;\n  }\n\n  /**\n   * This session's scoping tags (e.g. `{ projectPath }`), stamped onto every\n   * thread it creates. Returns a copy; empty when the session is unscoped.\n   */\n  getTags(): Record<string, string> {\n    return { ...this.#tags };\n  }\n\n  /**\n   * The scope this session's threads carry: what `thread.create()` stamps and\n   * what thread selection filters on. Both must read it here — computing it on\n   * each side is what let selection drift off the controller-global state while","sourceCodeStart":2887,"sourceCodeEnd":2923,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent-controller/session.ts#L2887-L2923","documentation":"The AgentController accepts a workspace for session-scoped file/tool access, but it must be an actual Workspace instance (not a plain object, path string, or config). The constructor throws when a truthy workspace value is passed that fails the instanceof check, so misconfigured workspaces fail loudly at construction rather than at first tool call.","triggerScenarios":"Passing a raw object shaped like a Workspace, a filesystem path string, a config/options bag, or a Workspace from a different/incompatible package version to the session/controller constructor.","commonSituations":"Version mismatch where Workspace moved packages; passing workspace root path string instead of new Workspace(...); JSON-deserialized workspace config lacking the class prototype.","solutions":["Construct a real Workspace instance (new Workspace(...)) from the same package version the core uses.","If accepting a path from config, wrap it: new Workspace(path).","Verify the import source of Workspace matches the one AgentController instanceof-checks (no duplicate package installs)."],"exampleFix":"// before\nnew AgentControllerSession({ workspace: '/my/project' }); // throws\n// after\nimport { Workspace } from '@mastra/core/workspace';\nnew AgentControllerSession({ workspace: new Workspace('/my/project') });","handlingStrategy":"validation","validationCode":"if (workspace !== undefined && !(workspace instanceof Workspace)) {\n  throw new Error('workspace must be a Workspace instance; wrap paths with new Workspace(path)');\n}","typeGuard":"function isWorkspace(w: unknown): w is Workspace {\n  return w instanceof Workspace;\n}","tryCatchPattern":"try {\n  const session = new AgentControllerSession({ workspace });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('valid Workspace instance')) {\n    const session = new AgentControllerSession({ workspace: new Workspace(workspace as string) });\n  } else throw e;\n}","preventionTips":["Always pass new Workspace(...) instances, never paths or plain objects","Keep @mastra/core workspace package versions aligned to avoid duplicate-class instanceof failures","Normalize config input (string path -> Workspace) at the config boundary","Add a unit test asserting the constructor rejects invalid workspace values"],"tags":["configuration","type-error","workspace"],"backgroundTag":"invalid-argument-type","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}