{"record":{"id":"6141cbccdbc46ba7","repo":"mastra-ai/mastra","slug":"google-rbac-rolemapping-is-required","errorCode":null,"errorMessage":"Google RBAC roleMapping is required.","messagePattern":"Google RBAC roleMapping is required\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"auth/google/src/rbac-provider.ts","lineNumber":41,"sourceCode":"interface GroupsListResponse {\n  groups?: GoogleWorkspaceGroup[];\n  nextPageToken?: string;\n}\n\nexport class MastraRBACGoogle implements IRBACProvider<GoogleUser> {\n  private options: MastraRBACGoogleOptions;\n  private rolesCache: LRUCache<string, Promise<string[]>>;\n  private accessToken?: string;\n  private tokenExpiresAt = 0;\n  private tokenRefreshPromise?: Promise<string>;\n\n  get roleMapping(): RoleMapping {\n    return this.options.roleMapping;\n  }\n\n  constructor(options: MastraRBACGoogleOptions) {\n    if (!options.roleMapping) {\n      throw new Error('Google RBAC roleMapping is required.');\n    }\n\n    this.options = options;\n    this.accessToken = options.accessToken;\n    this.rolesCache = new LRUCache<string, Promise<string[]>>({\n      max: options.cache?.maxSize ?? DEFAULT_CACHE_MAX_SIZE,\n      ttl: options.cache?.ttlMs ?? DEFAULT_CACHE_TTL_MS,\n    });\n  }\n\n  async getRoles(user: GoogleUser): Promise<string[]> {\n    if (Array.isArray(user.groups)) {\n      return user.groups;\n    }\n\n    const userKey = this.resolveUserKey(user);\n    if (!userKey) {\n      return [];","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/auth/google/src/rbac-provider.ts#L23-L59","documentation":"Thrown synchronously in the MastraRBACGoogle constructor when the options object has no roleMapping. The provider maps Google Workspace group emails to Mastra roles/permissions via this mapping, so it is mandatory; without it the RBAC provider cannot resolve permissions.","triggerScenarios":"new MastraRBACGoogle({...}) called with options.roleMapping undefined or null — e.g. omitted entirely, loaded from env/config that failed to parse, or passing an empty variable.","commonSituations":"Config typo (roleMappings vs roleMapping); wiring RBAC options from an untyped JSON/env source where the key is missing; building options conditionally and skipping the mapping; upgrading and not noticing roleMapping became required.","solutions":["Pass a roleMapping object (group email -> roles/permissions, plus optional '_default') in MastraRBACGoogle options.","If options come from env/config, validate the mapping is present and non-empty before constructing the provider.","Check for key spelling mismatches (roleMapping vs roleMappings) in your config loader.","Fall back to a sensible default mapping if you intend a no-op provider (e.g. { _default: [] })."],"exampleFix":"// before\nconst rbac = new MastraRBACGoogle({ accessToken: token });\n// after\nconst rbac = new MastraRBACGoogle({\n  accessToken: token,\n  roleMapping: {\n    'eng@mycompany.com': ['admin'],\n    '_default': ['viewer'],\n  },\n});","handlingStrategy":"validation","validationCode":"function assertRoleMapping(opts: { roleMapping?: Record<string, unknown> }): void {\n  if (!opts.roleMapping || typeof opts.roleMapping !== 'object' || Object.keys(opts.roleMapping).length === 0) {\n    throw new Error('MastraRBACGoogle requires a non-empty roleMapping');\n  }\n}\n// call before: new MastraRBACGoogle(options)","typeGuard":"function hasRoleMapping(o: unknown): o is { roleMapping: Record<string, unknown> } {\n  return typeof o === 'object' && o !== null && 'roleMapping' in o && typeof (o as any).roleMapping === 'object' && (o as any).roleMapping !== null;\n}","tryCatchPattern":"let rbac: MastraRBACGoogle;\ntry {\n  rbac = new MastraRBACGoogle(options);\n} catch (err) {\n  if (err instanceof Error && err.message === 'Google RBAC roleMapping is required.') {\n    throw new Error('Startup config error: provide roleMapping in MastraRBACGoogle options');\n  }\n  throw err;\n}","preventionTips":["Construct the provider at startup (fail fast) rather than lazily on first request","Type options with a non-optional roleMapping field so TS catches omissions at compile time","When loading options from JSON/env, validate required keys before constructing","Watch for roleMapping vs roleMappings key typos in config"],"tags":["configuration","rbac","google","validation"],"backgroundTag":"missing-required-option","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}