{"record":{"id":"f9dc11035327dc95","repo":"pentaho/pentaho-kettle","slug":"mail-exception-couldnotfindauthenticationuserfield","errorCode":null,"errorMessage":"Mail.Exception.CouldnotFindAuthenticationUserField","messagePattern":"Mail\\.Exception\\.CouldnotFindAuthenticationUserField","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/mail/impl/src/main/java/org/pentaho/di/trans/steps/mail/Mail.java","lineNumber":377,"sourceCode":"    // Authentication\n    if ( meta.isUsingAuthentication().equals( MailMeta.AUTENTICATION_BASIC ) ) {\n      // cache the position of the Authentication password field\n      if ( data.indexOfAuthenticationPass < 0 ) {\n        String realAuthenticationPassword = Utils.resolvePassword( variables, meta.getAuthenticationPassword() );\n        data.indexOfAuthenticationPass = data.previousRowMeta.indexOfValue( realAuthenticationPassword );\n        if ( data.indexOfAuthenticationPass < 0 ) {\n          throw new KettleException( BaseMessages.getString(\n            PKG, \"Mail.Exception.CouldnotFindAuthenticationPassField\", realAuthenticationPassword ) );\n        }\n      }\n    }\n    // cache the position of the Authentication user field\n    if ( meta.isUsingAuthentication().equals( MailMeta.AUTENTICATION_BASIC ) || meta.isUsingAuthentication().equals( MailMeta.AUTENTICATION_OAUTH ) ) {\n      if ( data.indexOfAuthenticationUser < 0 ) {\n        String realAuthenticationUser = meta.getAuthenticationUser();\n        data.indexOfAuthenticationUser = data.previousRowMeta.indexOfValue( realAuthenticationUser );\n        if ( data.indexOfAuthenticationUser < 0 ) {\n          throw new KettleException( BaseMessages.getString(\n            PKG, \"Mail.Exception.CouldnotFindAuthenticationUserField\", realAuthenticationUser ) );\n        }\n      }\n    }\n    // Mail Subject\n    if ( !Utils.isEmpty( meta.getSubject() ) ) {\n      // cache the position of the subject field\n      if ( data.indexOfSubject < 0 ) {\n        String realSubject = meta.getSubject();\n        data.indexOfSubject = data.previousRowMeta.indexOfValue( realSubject );\n        if ( data.indexOfSubject < 0 ) {\n          throw new KettleException( BaseMessages.getString(\n            PKG, \"Mail.Exception.CouldnotFindSubjectField\", realSubject ) );\n        }\n      }\n    }\n    // Mail Comment\n    if ( !Utils.isEmpty( meta.getComment() ) ) {","sourceCodeStart":359,"sourceCodeEnd":395,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/mail/impl/src/main/java/org/pentaho/di/trans/steps/mail/Mail.java#L359-L395","documentation":"The Mail step is configured for BASIC or OAUTH authentication and needs the authentication user name from a field in the incoming row, but no field matching meta.getAuthenticationUser() exists in the row metadata. The lookup in cacheFieldsPosition returns -1 and this KettleException is thrown.","triggerScenarios":"Authentication mode is 'Basic' or 'OAuth', and data.previousRowMeta.indexOfValue(realAuthenticationUser) < 0 because the configured user field name does not exist in the input stream.","commonSituations":"User field name typo; upstream step deleted/renamed the field; step copied from another transformation where the input schema differed.","solutions":["Check the 'Authentication user' field name in the Mail step against the actual input row fields.","Preview the incoming hop to confirm the user field reaches this step.","If the username is constant, use the static user setting rather than a field reference."],"exampleFix":"// before\n// Authentication user field: \"usr\" but stream contains \"username\"\n// after\n// Set the Authentication user field to \"username\" (exact match of the stream field)","handlingStrategy":"validation","validationCode":"if ((meta.isUsingAuthentication().equals(MailMeta.AUTENTICATION_BASIC)\n    || meta.isUsingAuthentication().equals(MailMeta.AUTENTICATION_OAUTH))\n    && rowMeta.indexOfValue(meta.getAuthenticationUser()) < 0) {\n  throw new KettleException(\"Auth user field not found: \" + meta.getAuthenticationUser());\n}","typeGuard":null,"tryCatchPattern":"try { sendMail(); } catch (KettleException e) { if (e.getMessage().contains(\"CouldnotFindAuthenticationUserField\")) { logError(\"Verify the authentication user field name in the Mail step\"); } throw e; }","preventionTips":["Select the user field from the dropdown in the step dialog rather than typing it.","Include an explicit field check upstream when the transformation schema can change.","Keep authentication fields stable across transformation refactors."],"tags":["kettle","pentaho","mail-step","authentication"],"backgroundTag":"field-not-found-in-row","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}