{"record":{"id":"5d5a6aa8eb26de72","repo":"pentaho/pentaho-kettle","slug":"mail-exception-couldnotfindsubjectfield","errorCode":null,"errorMessage":"Mail.Exception.CouldnotFindSubjectField","messagePattern":"Mail\\.Exception\\.CouldnotFindSubjectField","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/mail/impl/src/main/java/org/pentaho/di/trans/steps/mail/Mail.java","lineNumber":389,"sourceCode":"    // 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() ) ) {\n      // cache the position of the comment field\n      if ( data.indexOfComment < 0 ) {\n        String realComment = meta.getComment();\n        data.indexOfComment = data.previousRowMeta.indexOfValue( realComment );\n        if ( data.indexOfComment < 0 ) {\n          throw new KettleException( BaseMessages.getString(\n            PKG, \"Mail.Exception.CouldnotFindCommentField\", realComment ) );\n        }\n      }\n    }\n\n    if ( meta.isAttachContentFromField() ) {","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/mail/impl/src/main/java/org/pentaho/di/trans/steps/mail/Mail.java#L371-L407","documentation":"The Mail step is configured to take the mail subject from a field, but the configured subject field name was not found in the incoming row's metadata. cacheFieldsPosition throws this KettleException when the indexOfValue lookup returns -1.","triggerScenarios":"meta.getSubject() is non-empty (treated as a field name) and data.previousRowMeta has no field with that exact name.","commonSituations":"Developer typed the subject text directly into the subject field setting (which expects a field name); upstream column renamed; case mismatch.","solutions":["Verify the 'Subject' setting holds a field name that exists in the input stream, exactly.","If the subject is static text, clear the Subject field and supply the subject via a static subject setting or an upstream step.","Preview the input rows to confirm the subject-producing field is present."],"exampleFix":"// before\n// Subject field: \"Monthly Report\" (literal text, not a field)\n// after\n// Add upstream step producing field \"mail_subject\" with value 'Monthly Report',\n// then set the Subject field to \"mail_subject\"","handlingStrategy":"validation","validationCode":"if (meta.getSubject() != null && !meta.getSubject().isEmpty()\n    && rowMeta.indexOfValue(meta.getSubject()) < 0) {\n  throw new KettleException(\"Subject field not found in input stream: \" + meta.getSubject());\n}","typeGuard":null,"tryCatchPattern":"try { sendMail(); } catch (KettleException e) { if (e.getMessage().contains(\"CouldnotFindSubjectField\")) { logError(\"Subject setting must reference an existing stream field\"); } throw e; }","preventionTips":["Remember the Subject setting expects a FIELD name, not literal text.","Preview rows before running the transformation end-to-end.","Generate the subject in an upstream step (e.g. 'User Defined Java Expression') with a stable field name."],"tags":["kettle","pentaho","mail-step","field-lookup"],"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"}