mastra-ai/mastra · error · HTTPException

Permission denied

Error message

Permission denied

What it means

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.

Source

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

  if ('name' in error && error.name === 'PermissionError') return true;

  return false;
}

/**
 * Workspace-specific error handler.
 * Converts filesystem errors to appropriate HTTP status codes,
 * then falls back to generic handler.
 */
function handleWorkspaceError(error: unknown, defaultMessage: string): never {
  if (isFilesystemNotFoundError(error)) {
    const message = error instanceof Error ? error.message : 'Not found';
    throw new HTTPException(404, { message });
  }
  if (isFilesystemPermissionError(error)) {
    const message = error instanceof Error ? error.message : 'Permission denied';
    throw new HTTPException(403, { message });
  }
  return handleError(error, defaultMessage);
}

/**
 * Throws if workspace v1 is not supported by the current version of @mastra/core.
 */
function requireWorkspaceV1Support(): void {
  if (!coreFeatures.has('workspaces-v1')) {
    throw new HTTPException(501, {
      message: 'Workspace v1 not supported by this version of @mastra/core. Please upgrade to a newer version.',
    });
  }
}

/**
 * Get a workspace by ID from Mastra's workspace registry.
 *

View on GitHub (pinned to 75dd419e61)

Solutions

1. Fix ownership/permissions on the workspace storage directory (chown/chmod) for the server process user
2. Ensure the volume is mounted read-write if writes are expected
3. Run the server under a user with access to the configured workspace root

Example fix

// before
volumes: ["./workspace:/workspace:ro"]
// after
volumes: ["./workspace:/workspace:rw"]

await fs.promises.access(path, fs.constants.W_OK).catch(() => { throw new Error(`No write permission for ${path}`); });

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; }

When it happens

Trigger: 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.

Common situations: Docker/Kubernetes containers running as non-root with volume mounts owned by another UID; read-only mounted volumes; overly restrictive chmod on workspace directories.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Attaching a database requires the admin role in your organiz
• readFile ${path} failed (exit ${result.exitCode}): ${result.
• One or more process memory diagnostic artifact writes failed
• You need the admin role in this organization to manage datab
• Failed to create directory: ${errorMessage}

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