{"record":{"id":"06bcbd4a6ed9c787","repo":"mastra-ai/mastra","slug":"permission-denied","errorCode":null,"errorMessage":"Permission denied","messagePattern":"Permission denied","errorType":"http","errorClass":"HTTPException","httpStatus":403,"severity":"error","filePath":"packages/server/src/server/handlers/workspace.ts","lineNumber":128,"sourceCode":"\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}\n\n/**\n * Get a workspace by ID from Mastra's workspace registry.\n *","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workspace.ts#L110-L146","documentation":"Workspace route error handler converting filesystem permission errors into HTTP 403 with the underlying message (or fallback 'Permission denied'). Raised when the server's filesystem access to a workspace path is denied by OS permissions.","triggerScenarios":"Server process user lacks read/write/execute permission on the workspace directory or file; attempting to write/delete in a read-only volume; path resolves to a protected system location.","commonSituations":"Docker/Kubernetes containers running as non-root with volume mounts owned by another UID; read-only mounted volumes; overly restrictive chmod on workspace directories.","solutions":["Fix ownership/permissions on the workspace storage directory (chown/chmod) for the server process user","Ensure the volume is mounted read-write if writes are expected","Run the server under a user with access to the configured workspace root"],"exampleFix":"// before\nvolumes: [\"./workspace:/workspace:ro\"]\n// after\nvolumes: [\"./workspace:/workspace:rw\"]","handlingStrategy":"try-catch","validationCode":"await fs.promises.access(path, fs.constants.W_OK).catch(() => { throw new Error(`No write permission for ${path}`); });","typeGuard":null,"tryCatchPattern":"try { await workspaceFs.write(path, data); } catch (e) { if (isHttpException(e, 403)) console.error('Filesystem permission denied; fix server process access to workspace dir'); else throw e; }","preventionTips":["Verify the server process UID can access the workspace volume at startup","Avoid read-only mounts for write workloads","Set explicit ownership/permissions in container images"],"tags":["http-403","filesystem","permissions"],"backgroundTag":"permission-denied","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}