{"record":{"id":"7563fb52392f0b9b","repo":"mastra-ai/mastra","slug":"not-found-7563fb","errorCode":null,"errorMessage":"Not found","messagePattern":"Not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/workspace.ts","lineNumber":124,"sourceCode":"function isFilesystemPermissionError(error: unknown): boolean {\n  if (!error || typeof error !== 'object') return false;\n\n  if ('code' in error && error.code === 'EACCES') return true;\n\n  if ('name' in error && error.name === 'PermissionError') return true;\n\n  return false;\n}\n\n/**\n * Workspace-specific error handler.\n * Converts filesystem errors to appropriate HTTP status codes,\n * then falls back to generic handler.\n */\nfunction handleWorkspaceError(error: unknown, defaultMessage: string): never {\n  if (isFilesystemNotFoundError(error)) {\n    const message = error instanceof Error ? error.message : 'Not found';\n    throw new HTTPException(404, { message });\n  }\n  if (isFilesystemPermissionError(error)) {\n    const message = error instanceof Error ? error.message : 'Permission denied';\n    throw new HTTPException(403, { message });\n  }\n  return handleError(error, defaultMessage);\n}\n\n/**\n * Throws if workspace v1 is not supported by the current version of @mastra/core.\n */\nfunction requireWorkspaceV1Support(): void {\n  if (!coreFeatures.has('workspaces-v1')) {\n    throw new HTTPException(501, {\n      message: 'Workspace v1 not supported by this version of @mastra/core. Please upgrade to a newer version.',\n    });\n  }\n}","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workspace.ts#L106-L142","documentation":"Workspace route error handler that converts filesystem 'not found' errors into HTTP 404 with the underlying error message (or the fallback 'Not found'). Raised by workspace list/get and workspace filesystem read/write/list/delete routes when the target workspace or file path does not exist.","triggerScenarios":"GET a workspace ID that is not registered; reading/writing/deleting a file path under the workspace that does not exist; listing a workspace directory that was removed.","commonSituations":"Stale workspace IDs cached in clients after deletion; typos in file paths (paths outside the workspace root); assuming files exist before first write.","solutions":["Verify the workspace ID via the list-workspaces endpoint before filesystem operations","Check the exact file path (case-sensitive) exists within the workspace","Create the file/directory first if the operation assumes prior existence"],"exampleFix":"// before\nawait client.workspace(wsId).file('data/config.json').read(); // file absent\n// after\nawait client.workspace(wsId).file('data/config.json').write('{}');\nconst cfg = await client.workspace(wsId).file('data/config.json').read();","handlingStrategy":"try-catch","validationCode":"const ws = await client.listWorkspaces(); if (!ws.some(w => w.id === workspaceId)) throw new Error(`Workspace ${workspaceId} does not exist`);","typeGuard":"const workspaceExists = async (id: string) => (await client.listWorkspaces()).some(w => w.id === id);","tryCatchPattern":"try { await workspaceFs.read(path); } catch (e) { if (isHttpException(e, 404)) console.warn('Workspace/path not found:', path); else throw e; }","preventionTips":["Resolve workspace IDs dynamically rather than caching them","Check file existence before read/delete operations","Keep paths relative to the workspace root and validated"],"tags":["http-404","filesystem","workspace"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}