mastra-ai/mastra · error · HTTPException

Could not derive workspace ID from name. Please provide an e

Error message

Could not derive workspace ID from name. Please provide an explicit id.

What it means

On create, the workspace id defaults to the caller-provided id or toSlug(name). If neither yields a non-empty slug (empty/whitespace name whose slugification produces ''), the handler throws this 400. It refuses to invent an id so records stay addressable.

Source

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

    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' });
      }

      // Derive ID from name if not explicitly provided
      const id = providedId || toSlug(name);

      if (!id) {
        throw new HTTPException(400, {
          message: 'Could not derive workspace ID from name. Please provide an explicit id.',
        });
      }

      // Check if workspace with this ID already exists
      const existing = await workspaceStore.getById(id);
      if (existing) {
        throw new HTTPException(409, { message: `Workspace with id ${id} already exists` });
      }

      // Force authorId from the authenticated caller; ignore any body-provided value.
      // No caller (auth not configured) leaves authorId undefined so legacy
      // single-user setups continue to behave as today.
      const authorId = getCallerAuthorId(requestContext) ?? undefined;

      await workspaceStore.create({
        workspace: {
          id,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass an explicit id in the request body alongside name
2. Send a non-empty name containing alphanumeric characters so toSlug yields a usable slug
3. Trim/validate name client-side before submitting
4. Retry with corrected payload — this is a deterministic 400, not transient

Example fix

// before
await createWorkspace({ name: '   ' }); // slugifies to ''
// after
await createWorkspace({ name: 'Research Sandbox', id: 'research-sandbox' });

import { toSlug } from '@mastra/core'; // or local equivalent
export function resolveWorkspaceId(id?: string, name?: string): string {
  const derived = id || toSlug(name ?? '');
  if (!derived) throw new Error('Provide an explicit id or a non-empty alphanumeric name');
  return derived;
}

try {
  await createStoredWorkspace({ name });
} catch (e: any) {
  if (e.status === 400 && String(e.message).includes('Could not derive workspace ID')) {
    return createStoredWorkspace({ name, id: slugify(name.trim()) || crypto.randomUUID() });
  }
  throw e;
}

When it happens

Trigger: POST /api/stored/workspaces with no id and a name like ' ' or '///' (only characters stripped by slugification), producing an empty derived id.

Common situations: Programmatic creation with a name built from user input that ends up empty; forms submitting whitespace-only names; locale/emoji-only names depending on toSlug behavior; template code passing name: '' .

Related errors

• bad request: ${responseText}
• Invalid agent-builder action: ${actionId}. Valid actions are
• Invalid agent-builder action: ${actionId}
• Cannot delete the active version. Activate a different versi
• Agent ID is required

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