{"record":{"id":"ac4b084e660aa5b9","repo":"mastra-ai/mastra","slug":"workspace-not-found","errorCode":null,"errorMessage":"Workspace not found","messagePattern":"Workspace not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/workspace.ts","lineNumber":1426,"sourceCode":"// =============================================================================\n\nexport const WORKSPACE_SKILLS_SH_INSTALL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/workspaces/:workspaceId/skills-sh/install',\n  responseType: 'json',\n  pathParamSchema: workspaceIdPathParams,\n  bodySchema: skillsShInstallBodySchema,\n  responseSchema: skillsShInstallResponseSchema,\n  summary: 'Install skill from Skills API',\n  description: 'Installs a skill by fetching files from the Skills API and writing to workspace filesystem.',\n  tags: ['Workspace', 'Skills'],\n  handler: async ({ mastra, workspaceId, owner, repo, skillName, mount }) => {\n    try {\n      requireWorkspaceV1Support();\n\n      const workspace = await getWorkspaceById(mastra, workspaceId);\n      if (!workspace) {\n        throw new HTTPException(404, { message: 'Workspace not found' });\n      }\n\n      if (!workspace.filesystem) {\n        throw new HTTPException(400, { message: 'Workspace filesystem not available' });\n      }\n\n      if (workspace.filesystem.readOnly) {\n        throw new HTTPException(403, { message: 'Workspace is read-only' });\n      }\n\n      // Fetch skill files from the Skills API\n      const result = await fetchSkillFiles(owner, repo, skillName);\n      if (!result || result.files.length === 0) {\n        throw new HTTPException(404, {\n          message: `Could not find skill \"${skillName}\" in ${owner}/${repo}.`,\n        });\n      }\n","sourceCodeStart":1408,"sourceCodeEnd":1444,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workspace.ts#L1408-L1444","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"// before\nawait installSkill({ workspaceId: staleId, ... }); // 404\n// after\nconst ws = await listWorkspaces();\nawait installSkill({ workspaceId: ws[0].id, ... });","handlingStrategy":"validation","validationCode":"const ws = await getWorkspace(workspaceId); // list/lookup first\nif (!ws) throw new Error(`Workspace ${workspaceId} does not exist; pick a valid id before installing skills.`);","typeGuard":"function workspaceExists(ws: unknown): ws is { id: string; filesystem?: unknown } {\n  return !!ws && typeof (ws as any).id === 'string';\n}","tryCatchPattern":"try {\n  await installSkill({ workspaceId, ... });\n} catch (e) {\n  if (/Workspace not found/.test(String(e))) {\n    const [current] = await listWorkspaces();\n    return installSkill({ workspaceId: current.id, ... });\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["http-404","not-found","workspace","invalid-id"],"backgroundTag":"workspace-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}