What causes "Workspace not found" in mastra-ai/mastra?

Re-fetch the workspace list from the API and use a current, valid workspaceId.

mastra-ai/mastra · error · HTTPException

Workspace not found

Error message

Workspace not found

What it means

HTTPException 404 thrown when getWorkspaceById(mastra, workspaceId) returns no workspace for the given ID during a skill-install handler call. The handler requires a valid workspace record before touching its filesystem.

Source

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

// =============================================================================

export const WORKSPACE_SKILLS_SH_INSTALL_ROUTE = createRoute({
  method: 'POST',
  path: '/workspaces/:workspaceId/skills-sh/install',
  responseType: 'json',
  pathParamSchema: workspaceIdPathParams,
  bodySchema: skillsShInstallBodySchema,
  responseSchema: skillsShInstallResponseSchema,
  summary: 'Install skill from Skills API',
  description: 'Installs a skill by fetching files from the Skills API and writing to workspace filesystem.',
  tags: ['Workspace', 'Skills'],
  handler: async ({ mastra, workspaceId, owner, repo, skillName, mount }) => {
    try {
      requireWorkspaceV1Support();

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

      if (!workspace.filesystem) {
        throw new HTTPException(400, { message: 'Workspace filesystem not available' });
      }

      if (workspace.filesystem.readOnly) {
        throw new HTTPException(403, { message: 'Workspace is read-only' });
      }

      // Fetch skill files from the Skills API
      const result = await fetchSkillFiles(owner, repo, skillName);
      if (!result || result.files.length === 0) {
        throw new HTTPException(404, {
          message: `Could not find skill "${skillName}" in ${owner}/${repo}.`,
        });
      }

View on GitHub (pinned to 75dd419e61)

Solutions

Re-fetch the workspace list from the API and use a current, valid workspaceId.
Confirm the server's storage backend is correctly configured and points at the environment that owns the workspace.
If the workspace was deleted, recreate it before installing skills.

Example fix

// before
await installSkill({ workspaceId: staleId, ... }); // 404
// after
const ws = await listWorkspaces();
await installSkill({ workspaceId: ws[0].id, ... });

Defensive patterns

Strategy: validation

Validate before calling

const ws = await getWorkspace(workspaceId); // list/lookup first
if (!ws) throw new Error(`Workspace ${workspaceId} does not exist; pick a valid id before installing skills.`);

Type guard

function workspaceExists(ws: unknown): ws is { id: string; filesystem?: unknown } {
  return !!ws && typeof (ws as any).id === 'string';
}

Try / catch

try {
  await installSkill({ workspaceId, ... });
} catch (e) {
  if (/Workspace not found/.test(String(e))) {
    const [current] = await listWorkspaces();
    return installSkill({ workspaceId: current.id, ... });
  }
  throw e;
}

Prevention

Always resolve workspaceId from a fresh list call instead of caching long-lived IDs.
Delete stale workspace references when workspaces are torn down.
Keep dev/prod workspaces separated to avoid cross-environment ID mixups.

When it happens

Trigger: POSTing to the workspace install-skill route with a workspaceId that does not exist, was deleted, or belongs to a different Mastra instance/storage backend.

Common situations: Stale workspace ID cached in the client after a workspace was removed; wrong storage backend configured so the workspace record is not visible; ID copy/paste from another environment (dev vs prod).

Related errors

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