{"record":{"id":"63ee3d55c48422ba","repo":"mastra-ai/mastra","slug":"you-need-the-admin-role-in-this-organization-to-ma","errorCode":null,"errorMessage":"You need the admin role in this organization to manage databases.","messagePattern":"You need the admin role in this organization to manage databases\\.","errorType":"exception","errorClass":"Error","httpStatus":403,"severity":"error","filePath":"packages/cli/src/commands/db/platform-api.ts","lineNumber":70,"sourceCode":"};\n\nconst ADMIN_REQUIRED_MESSAGE = 'You need the admin role in this organization to manage databases.';\n\nfunction getApiUrl(): string {\n  return process.env.MASTRA_PLATFORM_API_URL || 'https://platform.mastra.ai';\n}\n\nasync function readErrorDetail(resp: Response): Promise<string | undefined> {\n  try {\n    return extractApiErrorDetail(await resp.json());\n  } catch {\n    return undefined;\n  }\n}\n\nasync function handleFailure(resp: Response, message: string): Promise<never> {\n  if (resp.status === 403) {\n    throw new Error(ADMIN_REQUIRED_MESSAGE);\n  }\n  throwApiError(message, resp.status, await readErrorDetail(resp));\n}\n\nexport async function fetchDatabases(token: string, orgId: string, projectId: string): Promise<ProjectDatabase[]> {\n  const resp = await platformFetch(`${getApiUrl()}/v1/server/projects/${projectId}/databases`, {\n    headers: authHeaders(token, orgId),\n  });\n\n  if (!resp.ok) {\n    await handleFailure(resp, 'Failed to fetch databases');\n  }\n\n  const data = (await resp.json()) as { databases: ProjectDatabase[] };\n  return data.databases;\n}\n\n/**","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/db/platform-api.ts#L52-L88","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Log in as (or ask an org admin for) a token belonging to a user with the admin role in that organization","Verify your role in the Mastra Studio org settings and request admin access","Confirm the --org / orgId used matches an organization where your account is admin","Re-authenticate with `mastra login` if you recently gained admin role and hold a stale token"],"exampleFix":"// before\nconst resp = await platformFetch(url, { headers: { Authorization: `Bearer ${memberToken}` } });\nawait fetchDatabases(token, orgId, projectId); // 403 -> admin role error\n// after\n// grant admin role to the account owning `token` in the org, or swap in an admin token\nconst resp = await platformFetch(url, { headers: { Authorization: `Bearer ${adminToken}` } });","handlingStrategy":"try-catch","validationCode":"// Before running db commands, confirm admin access by listing orgs/roles you can verify:\nconst 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'\nif (!isAdmin) throw new Error('Admin role required in org ' + orgId + ' before managing databases');","typeGuard":"function isAdminRole(role: string | undefined | null): role is 'admin' {\n  return role === 'admin';\n}","tryCatchPattern":"try {\n  const dbs = await fetchDatabases(token, orgId, projectId);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('admin role')) {\n    // surface guidance: request admin role or switch to an admin token\n  } else throw err;\n}","preventionTips":["Verify your org role in Studio before running db admin commands","Use dedicated admin tokens for CI db management jobs","Re-login after role changes so the token reflects new permissions","Don't mix read-only service tokens with db-mutation commands"],"tags":["authorization","permissions","http-403","cli"],"backgroundTag":"insufficient-role-permissions","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}