mastra-ai/mastra · error · Error

You need the admin role in this organization to manage datab

Error message

You need the admin role in this organization to manage databases.

What it means

The Mastra CLI's database commands (list, show, attach, delete, connection) all route HTTP failures through handleFailure. When the platform API returns HTTP 403, the CLI discards the server's error detail and throws this fixed message because a 403 on a project-database endpoint specifically means the authenticated token belongs to a user without the admin role in that organization. Database management is an admin-only capability, so non-admin members are blocked up front.

Source

Thrown at packages/cli/src/commands/db/platform-api.ts:70

};

const ADMIN_REQUIRED_MESSAGE = 'You need the admin role in this organization to manage databases.';

function getApiUrl(): string {
  return process.env.MASTRA_PLATFORM_API_URL || 'https://platform.mastra.ai';
}

async function readErrorDetail(resp: Response): Promise<string | undefined> {
  try {
    return extractApiErrorDetail(await resp.json());
  } catch {
    return undefined;
  }
}

async function handleFailure(resp: Response, message: string): Promise<never> {
  if (resp.status === 403) {
    throw new Error(ADMIN_REQUIRED_MESSAGE);
  }
  throwApiError(message, resp.status, await readErrorDetail(resp));
}

export async function fetchDatabases(token: string, orgId: string, projectId: string): Promise<ProjectDatabase[]> {
  const resp = await platformFetch(`${getApiUrl()}/v1/server/projects/${projectId}/databases`, {
    headers: authHeaders(token, orgId),
  });

  if (!resp.ok) {
    await handleFailure(resp, 'Failed to fetch databases');
  }

  const data = (await resp.json()) as { databases: ProjectDatabase[] };
  return data.databases;
}

/**

View on GitHub (pinned to 75dd419e61)

Solutions

1. Log in as (or ask an org admin for) a token belonging to a user with the admin role in that organization
2. Verify your role in the Mastra Studio org settings and request admin access
3. Confirm the --org / orgId used matches an organization where your account is admin
4. Re-authenticate with `mastra login` if you recently gained admin role and hold a stale token

Example fix

// before
const resp = await platformFetch(url, { headers: { Authorization: `Bearer ${memberToken}` } });
await fetchDatabases(token, orgId, projectId); // 403 -> admin role error
// after
// grant admin role to the account owning `token` in the org, or swap in an admin token
const resp = await platformFetch(url, { headers: { Authorization: `Bearer ${adminToken}` } });

// Before running db commands, confirm admin access by listing orgs/roles you can verify:
const isAdmin = typeof process.env.MASTRA_TOKEN === 'string' && process.env.MASTRA_TOKEN.length > 0 && await confirmAdminRole(token, orgId); // e.g. fetch org members and check your role === 'admin'
if (!isAdmin) throw new Error('Admin role required in org ' + orgId + ' before managing databases');

function isAdminRole(role: string | undefined | null): role is 'admin' {
  return role === 'admin';
}

try {
  const dbs = await fetchDatabases(token, orgId, projectId);
} catch (err) {
  if (err instanceof Error && err.message.includes('admin role')) {
    // surface guidance: request admin role or switch to an admin token
  } else throw err;
}

When it happens

Trigger: Any of fetchDatabases, fetchDatabaseCatalog, attachDatabase, fetchDatabase, deleteDatabase, or fetchDatabaseConnection receives resp.status === 403 from the platform API — i.e., the token is valid and the org/project exists, but the user's role in the organization is not admin.

Common situations: Developers authenticating as a member/developer-role user instead of an org admin; running `mastra env db ...` in CI with a service token that has read-only scope; a teammate added to the org without elevated permissions trying to attach or delete a database.

Related errors

• You do not have permission to update this connection
• Attaching a database requires the admin role in your organiz
• No access to organization ${orgId}. Run: mastra auth orgs
• Failed to create directory: ${errorMessage}
• Failed to write scorer: ${errorMessage}

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