mastra-ai/mastra · error · HTTPException

Stored workspace with id ${storedWorkspaceId} not found

Error message

Stored workspace with id ${storedWorkspaceId} not found

What it means

The by-ID handler queried workspaceStore.getByIdResolved(id) and got null, meaning no stored workspace exists with that identifier. It throws a 404 (client-correct: the resource simply does not exist). Note the id is the stored record's id (slug), not a runtime workspace key.

Source

Thrown at packages/server/src/server/handlers/stored-workspaces.ts:124

  tags: ['Stored Workspaces'],
  requiresAuth: true,
  handler: async ({ mastra, storedWorkspaceId, requestContext }) => {
    try {
      const storage = mastra.getStorage();

      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }

      const workspaceStore = await storage.getStore('workspaces');
      if (!workspaceStore) {
        throw new HTTPException(500, { message: 'Workspaces storage domain is not available' });
      }

      const workspace = await workspaceStore.getByIdResolved(storedWorkspaceId);

      if (!workspace) {
        throw new HTTPException(404, { message: `Stored workspace with id ${storedWorkspaceId} not found` });
      }
      assertStoredResourceScope(workspace, await getStoredResourceScope(mastra, requestContext));

      // Throws 404 if the caller isn't the owner, admin, or `stored-workspaces:read[:<id>]` holder.
      assertReadAccess({
        requestContext,
        resource: 'stored-workspaces',
        resourceId: storedWorkspaceId,
        record: workspace,
      });

      return workspace;
    } catch (error) {
      return handleError(error, 'Error getting stored workspace');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

List stored workspaces (GET /api/stored/workspaces) to find the correct id
Recreate the workspace with POST /stored/workspaces if it was deleted
Check you are connected to the environment/database where the workspace was created
Pass the exact slug id (e.g. 'my-workspace') — it derives from name via toSlug when id is omitted at create time

Example fix

// before
await fetch('/api/stored/workspaces/my workspace v1'); // spaces/case wrong
// after
const { workspaces } = await fetch('/api/stored/workspaces').then(r => r.json());
const ws = workspaces.find(w => w.name === 'My Workspace v1');
await fetch(`/api/stored/workspaces/${ws.id}`);

Defensive patterns

Strategy: validation

Validate before calling

export async function assertWorkspaceExists(baseUrl: string, id: string) {
  const res = await fetch(`${baseUrl}/api/stored/workspaces/${encodeURIComponent(id)}`);
  if (res.status === 404) throw new Error(`Workspace '${id}' not found — list /api/stored/workspaces to find valid ids`);
  return res.json();
}

Type guard

function isStoredWorkspace(x: unknown): x is { id: string; name: string } {
  return !!x && typeof x === 'object' && typeof (x as any).id === 'string' && typeof (x as any).name === 'string';
}

Try / catch

try {
  return await getStoredWorkspace(id);
} catch (e: any) {
  if (e.status === 404 && String(e.message).includes('not found')) {
    const all = await listStoredWorkspaces();
    console.error(`Unknown id '${id}'. Known ids: ${all.workspaces.map(w => w.id).join(', ')}`);
  } else throw e;
}

Prevention

Discover ids via the list endpoint instead of hardcoding
Remember ids default to toSlug(name) at create time
Handle deletions by teammates — re-check existence before reuse
Confirm you are pointed at the right environment's database

When it happens

Trigger: GET /api/stored/workspaces/:storedWorkspaceId with an id that was never created, was deleted, or is misspelled; using a runtime workspace name instead of the stored slug id.

Common situations: Hardcoded id from an old database; workspace deleted via UI/API by a teammate; assuming auto-increment-style ids instead of the slugified name (toSlug(name) default); wrong environment's database (dev vs prod).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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