mastra-ai/mastra · error · MastraError

MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA

MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA

Error message

Agent workspaces must include agentId and agentName.

What it means

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.

Source

Thrown at packages/core/src/mastra/index.ts:3328

   * const workspace = new Workspace({
   *   id: 'project-workspace',
   *   name: 'Project Workspace',
   *   filesystem: new LocalFilesystem({ rootPath: './workspace' })
   * });
   * mastra.addWorkspace(workspace);
   * ```
   */
  public addWorkspace(
    workspace: AnyWorkspace,
    key?: string,
    metadata?: { source?: 'mastra' | 'agent'; agentId?: string; agentName?: string },
  ): void {
    if (!workspace) {
      throw createUndefinedPrimitiveError('workspace', workspace, key);
    }
    const source = metadata?.source ?? (metadata?.agentId || metadata?.agentName ? 'agent' : 'mastra');
    if (source === 'agent' && (!metadata?.agentId || !metadata?.agentName)) {
      throw new MastraError({
        id: 'MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA',
        domain: ErrorDomain.MASTRA,
        category: ErrorCategory.USER,
        text: 'Agent workspaces must include agentId and agentName.',
        details: { status: 400, workspaceId: key || workspace.id },
      });
    }
    const workspaceKey = key || workspace.id;
    if (this.#workspaces[workspaceKey]) {
      return;
    }

    this.#workspaces[workspaceKey] = {
      workspace,
      source,
      ...(metadata?.agentId ? { agentId: metadata.agentId } : {}),
      ...(metadata?.agentName ? { agentName: metadata.agentName } : {}),
    };

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass both metadata.agentId and metadata.agentName when registering an agent workspace.
2. If the workspace is not agent-owned, omit agentId/agentName and source so it defaults to source 'mastra'.
3. Set explicitly metadata.source='mastra' when registering a shared/global workspace.
4. Ensure the agent passes its own id and name when it self-registers its workspace.

Example fix

// before
mastra.addWorkspace('my-ws', workspace, { source: 'agent', agentId: 'agent-1' }); // missing agentName
// after
mastra.addWorkspace('my-ws', workspace, { source: 'agent', agentId: 'agent-1', agentName: 'My Agent' });

const source = metadata?.source ?? (metadata?.agentId || metadata?.agentName ? 'agent' : 'mastra');
if (source === 'agent' && (!metadata?.agentId || !metadata?.agentName)) {
  throw new Error('Agent workspaces require both agentId and agentName');
}
mastra.addWorkspace(key, workspace, metadata);

function isAgentWorkspaceMeta(m?: { source?: string; agentId?: string; agentName?: string }): m is { source: 'agent'; agentId: string; agentName: string } {
  return !!m && (m.source === 'agent' || !!m.agentId || !!m.agentName) && !!m.agentId && !!m.agentName;
}

try {
  mastra.addWorkspace(key, workspace, metadata);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA') {
    mastra.addWorkspace(key, workspace, { ...metadata, agentId: agent.id, agentName: agent.name });
    return;
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO
• heartbeatMs must be a finite number no greater than ${MAX_TI
• Expected a PEM-encoded public key or certificate string for
• terminationGraceMs must be greater than zero.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/63d303046a169fc2. Report an issue: GitHub.