mastra-ai/mastra · error · HTTPException

No workspace configured

Error message

No workspace configured

What it means

The index route (POST /workspaces/:workspaceId/index) throws this 404 when `getWorkspaceById(mastra, workspaceId)` returns no workspace — i.e. no workspace is registered under that ID (or none is configured at all). Indexing requires an existing workspace instance to delegate to workspace.index().

Source

Thrown at packages/server/src/server/handlers/workspace.ts:847

  path: '/workspaces/:workspaceId/index',
  responseType: 'json',
  pathParamSchema: workspaceIdPathParams,
  bodySchema: indexBodySchema,
  responseSchema: indexResponseSchema,
  summary: 'Index content for search',
  description: 'Indexes content for later search operations',
  tags: ['Workspace'],
  handler: async ({ mastra, path, content, metadata, workspaceId }) => {
    try {
      requireWorkspaceV1Support();

      if (!path || content === undefined) {
        throw new HTTPException(400, { message: 'Path and content are required' });
      }

      const workspace = await getWorkspaceById(mastra, workspaceId);
      if (!workspace) {
        throw new HTTPException(404, { message: 'No workspace configured' });
      }

      const canSearch = workspace.canBM25 || workspace.canVector;
      if (!canSearch) {
        throw new HTTPException(400, { message: 'Workspace does not have search configured' });
      }

      await workspace.index(path, content, { metadata });

      return {
        success: true,
        path,
      };
    } catch (error) {
      return handleWorkspaceError(error, 'Error indexing content');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a workspaceId that is actually registered on the running Mastra instance (check the workspace config passed to new Mastra({ workspaces: ... })).
2. Verify the server deployment includes workspace configuration (env-specific config drift).
3. List available workspaces or check server startup logs to confirm registration.
4. If the workspace is created dynamically, create/register it before calling index.

Example fix

// before
await fetch(`/api/workspaces/typo-ws/index`, { method: 'POST', ... });
// after
await fetch(`/api/workspaces/${registeredWorkspaceId}/index`, { method: 'POST', ... });

// Confirm the workspace exists before indexing
const wsRes = await fetch(`/api/workspaces/${wsId}/fs/list?path=${encodeURIComponent('/')}`);
if (wsRes.status === 404) {
  throw new Error(`Workspace ${wsId} is not configured on this server`);
}

function isKnownWorkspaceId(id: unknown): id is string {
  return typeof id === 'string' && knownWorkspaceIds.includes(id);
}

try {
  await indexContent(wsId, path, content);
} catch (e) {
  if (isHTTPException(e, 404) && e.message === 'No workspace configured') {
    // re-read workspace registration / correct the id, then retry once
  } else throw e;
}

When it happens

Trigger: POSTing to /workspaces/:id/index with a workspaceId that is not registered in the Mastra instance; Mastra constructed without any workspace; typo'd workspaceId path param; server started before workspace registration code ran.

Common situations: Copy-pasting a workspaceId from another deployment/environment; workspace configured only in local dev but not in the deployed Mastra config; version mismatch where the deployment doesn't support workspaces v1; client caching a stale workspaceId after server restart with new IDs.

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

• Agent with id ${agentId} not found
• No workspace filesystem configured
• No workspace filesystem configured
• No workspace with skills configured
• Model "${modelId}" is not available. Available models: ${ids

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