{"record":{"id":"1d44b180aaea2f79","repo":"RocketChat/Rocket.Chat","slug":"field-not-found-1d44b1","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/custom_oauth_server.js","lineNumber":319,"sourceCode":"\t\t\tconst response = await request.json();\n\n\t\t\treturn response.find((email) => email.primary === true)?.email;\n\t\t} catch (err) {\n\t\t\tconst error = new Error(`Failed to fetch emails from ${this.name} at ${this.emailPath}. ${err.message}`);\n\t\t\tthrow _.extend(error, { response: err.response });\n\t\t}\n\t}\n\n\tretrieveCredential(credentialToken, credentialSecret) {\n\t\treturn OAuth.retrieveCredential(credentialToken, credentialSecret);\n\t}\n\n\tgetUsername(data) {\n\t\ttry {\n\t\t\tconst value = fromTemplate(this.usernameField, data);\n\n\t\t\tif (!value) {\n\t\t\t\tthrow new Meteor.Error('field_not_found', `Username field \"${this.usernameField}\" not found in data`, data);\n\t\t\t}\n\t\t\treturn value;\n\t\t} catch (error) {\n\t\t\tthrow new Error('CustomOAuth: Failed to extract username', error.message);\n\t\t}\n\t}\n\n\tgetEmail(data) {\n\t\ttry {\n\t\t\tconst value = fromTemplate(this.emailField, data);\n\n\t\t\tif (!value) {\n\t\t\t\tthrow new Meteor.Error('field_not_found', `Email field \"${this.emailField}\" not found in data`, data);\n\t\t\t}\n\t\t\treturn value;\n\t\t} catch (error) {\n\t\t\tthrow new Error('CustomOAuth: Failed to extract email', error.message);\n\t\t}","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/auth-providers/custom-oauth/custom_oauth_server.js#L301-L337","documentation":"getUsername() resolves the configured usernameField against the identity payload via fromTemplate(); when the result is falsy it throws Meteor.Error('field_not_found', 'Username field \"<field>\" not found in data') with the payload attached as error details. Note that getUsername's own catch immediately re-wraps it (see the 'Failed to extract username' error), so this inner error is what appears in logs/debug output while clients see the wrapper.","triggerScenarios":"usernameField 'login' but the /me response only contains 'preferred_username'; nested path wrong ('user.login' vs flat 'login'); a '{{/regex/::path}}' formula whose regex does not match so getRegexpMatch returns undefined; provider changed its userinfo schema after an upgrade; usernameField left as empty string (configured constructor coerces missing values to '').","commonSituations":"Mapping fields by guessing claim names instead of inspecting the payload; provider API version bump renaming claims; Keycloak/Auth0 tenants with different claim sets; dot-path pointing at a key that renameInvalidProperties later mangles (dots become underscores).","solutions":["Enable CustomOAuth debug logging and read the 'Username field not found in data' record - it prints the exact payload keys","Correct usernameField to a dot path that exists, e.g. 'preferred_username' or 'user.login'","If using a regex formula, verify it matches the claim value and has exactly one capture group","Remove Username Field entirely to stop strict username extraction when the default behaviour is acceptable"],"exampleFix":"// before (Admin -> OAuth -> <service> -> Username Field): 'login'\n// payload has no 'login' key -> field_not_found: Username field \"login\" not found in data\n\n// after\npreferred_username   // key that actually exists in the identity payload","handlingStrategy":"validation","validationCode":"// before enabling strict mapping, verify the claim exists on a real payload\nconst sampleIdentity = await fetchIdentityWithTestToken();\nconst usernameField = 'user.login';\nconst resolved = usernameField.split('.').reduce<any>((o, k) => (o ? o[k] : undefined), sampleIdentity);\n\nif (!resolved) throw new Error(`usernameField '${usernameField}' does not resolve - do not enable it`);","typeGuard":"const hasClaim = (payload: Record<string, unknown>, path: string): boolean =>\n  path.split('.').reduce<unknown>((o, k) => (o && typeof o === 'object' ? (o as Record<string, unknown>)[k] : undefined), payload) != null;","tryCatchPattern":"try {\n  identity.username = strategy.getUsername(identity);\n} catch (error) {\n  logger.warn(error.message);\n  identity.username = identity.preferred_username ?? identity.sub; // unique fallback instead of failing login\n}","preventionTips":["Inspect the real identity payload before configuring any *Field mapping","Re-verify mappings after every provider upgrade","Map usernames to unique, stable claims - never display names","Remember clients see the wrapped error; the payload details live only in the inner error/debug log"],"tags":["oauth","custom-oauth","field-mapping","username"],"backgroundTag":"oauth-identity-field-mapping-failed","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}