{"record":{"id":"63d303046a169fc2","repo":"mastra-ai/mastra","slug":"mastra-add-workspace-missing-agent-metadata","errorCode":"MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA","errorMessage":"Agent workspaces must include agentId and agentName.","messagePattern":"Agent workspaces must include agentId and agentName\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":400,"severity":"error","filePath":"packages/core/src/mastra/index.ts","lineNumber":3328,"sourceCode":"   * const workspace = new Workspace({\n   *   id: 'project-workspace',\n   *   name: 'Project Workspace',\n   *   filesystem: new LocalFilesystem({ rootPath: './workspace' })\n   * });\n   * mastra.addWorkspace(workspace);\n   * ```\n   */\n  public addWorkspace(\n    workspace: AnyWorkspace,\n    key?: string,\n    metadata?: { source?: 'mastra' | 'agent'; agentId?: string; agentName?: string },\n  ): void {\n    if (!workspace) {\n      throw createUndefinedPrimitiveError('workspace', workspace, key);\n    }\n    const source = metadata?.source ?? (metadata?.agentId || metadata?.agentName ? 'agent' : 'mastra');\n    if (source === 'agent' && (!metadata?.agentId || !metadata?.agentName)) {\n      throw new MastraError({\n        id: 'MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA',\n        domain: ErrorDomain.MASTRA,\n        category: ErrorCategory.USER,\n        text: 'Agent workspaces must include agentId and agentName.',\n        details: { status: 400, workspaceId: key || workspace.id },\n      });\n    }\n    const workspaceKey = key || workspace.id;\n    if (this.#workspaces[workspaceKey]) {\n      return;\n    }\n\n    this.#workspaces[workspaceKey] = {\n      workspace,\n      source,\n      ...(metadata?.agentId ? { agentId: metadata.agentId } : {}),\n      ...(metadata?.agentName ? { agentName: metadata.agentName } : {}),\n    };","sourceCodeStart":3310,"sourceCodeEnd":3346,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/mastra/index.ts#L3310-L3346","documentation":"When registering a workspace via Mastra's addWorkspace (the registerWorkspace helper shown), a workspace whose metadata source resolves to 'agent' must carry both agentId and agentName; otherwise this USER-category 400 MastraError is thrown. It guarantees agent-owned workspaces are attributable to a specific named agent.","triggerScenarios":"Calling addWorkspace/registerWorkspace (or an agent registering its workspace) with metadata.source='agent' (explicitly, or implicitly by supplying only one of agentId/agentName) while agentId or agentName is missing/empty.","commonSituations":"Hand-rolling workspace registration and setting source:'agent' without the metadata fields; constructing metadata programmatically where agentId is set but agentName is undefined; an Agent subclass passing partial metadata to addWorkspace.","solutions":["Pass both metadata.agentId and metadata.agentName when registering an agent workspace.","If the workspace is not agent-owned, omit agentId/agentName and source so it defaults to source 'mastra'.","Set explicitly metadata.source='mastra' when registering a shared/global workspace.","Ensure the agent passes its own id and name when it self-registers its workspace."],"exampleFix":"// before\nmastra.addWorkspace('my-ws', workspace, { source: 'agent', agentId: 'agent-1' }); // missing agentName\n// after\nmastra.addWorkspace('my-ws', workspace, { source: 'agent', agentId: 'agent-1', agentName: 'My Agent' });","handlingStrategy":"validation","validationCode":"const source = metadata?.source ?? (metadata?.agentId || metadata?.agentName ? 'agent' : 'mastra');\nif (source === 'agent' && (!metadata?.agentId || !metadata?.agentName)) {\n  throw new Error('Agent workspaces require both agentId and agentName');\n}\nmastra.addWorkspace(key, workspace, metadata);","typeGuard":"function isAgentWorkspaceMeta(m?: { source?: string; agentId?: string; agentName?: string }): m is { source: 'agent'; agentId: string; agentName: string } {\n  return !!m && (m.source === 'agent' || !!m.agentId || !!m.agentName) && !!m.agentId && !!m.agentName;\n}","tryCatchPattern":"try {\n  mastra.addWorkspace(key, workspace, metadata);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA') {\n    mastra.addWorkspace(key, workspace, { ...metadata, agentId: agent.id, agentName: agent.name });\n    return;\n  }\n  throw e;\n}","preventionTips":["When registering agent-owned workspaces, always pass both agentId and agentName","Let non-agent workspaces default to source 'mastra' by omitting agent metadata","Centralize workspace registration so metadata is built in one helper"],"tags":["workspace","metadata","validation","configuration"],"backgroundTag":"missing-required-metadata","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}