{"record":{"id":"5f964fb5241b0f1b","repo":"RocketChat/Rocket.Chat","slug":"field-not-found","errorCode":"field_not_found","errorMessage":"Username field \"${this.usernameField}\" not found in data","messagePattern":"Username field \"(.+?)\" not found in data","errorType":"exception","errorClass":"Meteor.Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/lib/auth-providers/custom-oauth/customOAuth.ts","lineNumber":135,"sourceCode":"\n\t\tif (config.addAutopublishFields && typeof config.addAutopublishFields === 'object') {\n\t\t\tAccounts.addAutopublishFields(config.addAutopublishFields);\n\t\t}\n\n\t\tthis.name = name;\n\t\tthis.options = options;\n\t\tthis.config = config;\n\n\t\tthis.addHookToProcessUser();\n\t}\n\n\tgetUsername(data: Record<string, any>) {\n\t\ttry {\n\t\t\tconst value = fromTemplate(this.usernameField, data);\n\n\t\t\tif (!value) {\n\t\t\t\tlogger.debug({ msg: 'Username field not found in data', usernameField: this.usernameField, data });\n\t\t\t\tthrow new Meteor.Error('field_not_found', `Username field \"${this.usernameField}\" not found in data`);\n\t\t\t}\n\n\t\t\treturn value as string;\n\t\t} catch (error) {\n\t\t\tthrow new Error('CustomOAuth: Failed to extract username', { cause: error });\n\t\t}\n\t}\n\n\tgetEmail(data: Record<string, any>) {\n\t\ttry {\n\t\t\tconst value = fromTemplate(this.emailField, data);\n\n\t\t\tif (!value) {\n\t\t\t\tlogger.debug({ msg: 'Email field not found in data', emailField: this.emailField, data });\n\t\t\t\tthrow new Meteor.Error('field_not_found', `Email field \"${this.emailField}\" not found in data`);\n\t\t\t}\n\t\t\treturn value as string;\n\t\t} catch (error) {","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/auth-providers/custom-oauth/customOAuth.ts#L117-L153","documentation":"Thrown by CustomOAuthStrategy.getUsername when fromTemplate(this.usernameField, data) resolves to a falsy value — the configured username field/template does not exist in the identity payload returned by the OAuth provider's identity endpoint. It is a Meteor.Error('field_not_found') that is immediately re-wrapped (see error 636). The usernameField template may be a dot-path ('user.login') or a {{regex::path}} formula evaluated against the provider's response body.","triggerScenarios":"Custom OAuth login where usernameField is set (e.g., 'username') but the IdP's identity response uses a different shape ('login', 'preferred_username', nested 'user.login'); nested path wrong for providers like Keycloak/Nextcloud; {{regex}} formula whose capture group matches nothing so the result is undefined.","commonSituations":"Provider API version changed its /me response schema; field-mapping typo in the OAuth app config; scopes changed so claims disappeared; switching providers without updating field mappings.","solutions":["Inspect the actual identity payload (debug log 'Username field not found in data' includes the data) and correct usernameField to the real path (supports dot notation and {{regex::path}} templates)","If the provider hides the claim, extend the requested scopes so the username claim is returned","Alternatively clear usernameField so Rocket.Chat derives the username from other fields instead of hard-failing"],"exampleFix":"// before (provider returns { user: { login: 'jane' } })\nusernameField: 'username'\n\n// after\nusernameField: 'user.login'","handlingStrategy":"validation","validationCode":"import { fromTemplate } from './transform_helpers';\n\n// verify the mapping against a captured sample of the IdP /me response\nconst sample = await fetchIdentityEndpointSample();\nif (!fromTemplate('user.login', sample)) {\n\tthrow new Error('usernameField does not resolve against provider payload');\n}","typeGuard":"const resolvesIn = (template: string, data: Record<string, unknown>): boolean =>\n\tBoolean(fromTemplate(template, data));","tryCatchPattern":null,"preventionTips":["Capture one real /me payload per provider and keep field-mapping tests against it","Re-verify mappings after IdP upgrades that may change the userinfo schema","Leave usernameField empty when the provider has no stable username claim"],"tags":["custom-oauth","oauth","field-mapping","configuration"],"backgroundTag":"oauth-field-mapping-failed","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}