What causes "RegexEval.Exception.ErrorMatcherMissing" in pentaho/pentaho-kettle?

Open the Regex Eval dialog and select a field in 'The field to evaluate'

pentaho/pentaho-kettle · error · KettleStepException

RegexEval.Exception.ErrorMatcherMissing

Error message

RegexEval.Exception.ErrorMatcherMissing

What it means

RegexEval.processRow throws KettleStepException when no matcher field is configured (meta.getMatcher() == null). The step must know which incoming field's value the regular expression is evaluated against; without it, evaluation cannot proceed.

Solutions

Open the Regex Eval dialog and select a field in 'The field to evaluate'
Or call setMatcher("fieldName") on the meta before executing
Verify the step XML contains the matcher attribute if editing files directly

Example fix

// before
RegexEvalMeta meta = new RegexEvalMeta();
meta.setRegex("^A.*$");
// after
RegexEvalMeta meta = new RegexEvalMeta();
meta.setRegex("^A.*$");
if (meta.getMatcher() == null || meta.getMatcher().isEmpty()) {
  meta.setMatcher("inputField");
}

Defensive patterns

Strategy: validation

Validate before calling

RegexEvalMeta m = (RegexEvalMeta) stepMeta.getStepMetaInterface();
if (m.getMatcher() == null || m.getMatcher().trim().isEmpty()) throw new IllegalArgumentException("Matcher field must be set on Regex Eval step");

Type guard

boolean hasMatcher(RegexEvalMeta m) { return m.getMatcher() != null && !m.getMatcher().trim().isEmpty(); }

Try / catch

try { trans.execute(...); } catch (KettleException e) { if (e.getMessage().contains("ErrorMatcherMissing")) { logError("Configure 'The field to evaluate' in the Regex Eval step"); } throw e; }

Prevention

Set the matcher field immediately when configuring the step
Re-check step configuration after upstream field renames
Validate metadata programmatically before scheduled executions

When it happens

Trigger: Executing a Regex Eval step where the 'The field to evaluate' (matcher) dropdown was never set — detected on the first row processed.

Common situations: Building the step programmatically without calling setMatcher(); a transformation whose upstream field was renamed leaving the matcher unset; hand-edited XML dropping the matcher attribute.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/6c62380f0d1fe136. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/regexeval/RegexEval.java:100

          throw new KettleStepException( BaseMessages.getString(
            PKG, "RegexEval.Exception.ErrorResultFieldMissing" ) );
        }
        data.indexOfResultField = -1;
      } else {
        if ( meta.isReplacefields() ) {
          data.indexOfResultField = getInputRowMeta().indexOfValue( meta.getResultFieldName() );
        }
        if ( data.indexOfResultField < 0 ) {
          data.indexOfResultField = getInputRowMeta().size();
          captureIndex++;
        }
      }

      // Check if a Field (matcher) is given
      if ( meta.getMatcher() == null ) {
        // Matcher is missing !
        logError( BaseMessages.getString( PKG, "RegexEval.Log.ErrorMatcherMissing" ) );
        throw new KettleStepException( BaseMessages.getString( PKG, "RegexEval.Exception.ErrorMatcherMissing" ) );
      }

      // Cache the position of the Field
      data.indexOfFieldToEvaluate = getInputRowMeta().indexOfValue( meta.getMatcher() );
      if ( data.indexOfFieldToEvaluate < 0 ) {
        // The field is unreachable !
        logError( BaseMessages.getString( PKG, "RegexEval.Log.ErrorFindingField" ) + "[" + meta.getMatcher() + "]" );
        throw new KettleStepException( BaseMessages.getString( PKG, "RegexEval.Exception.CouldnotFindField", meta
          .getMatcher() ) );
      }

      // Cache the position of the CaptureGroups
      if ( meta.isAllowCaptureGroupsFlagSet() ) {
        data.positions = new int[meta.getFieldName().length];
        String[] fieldName = meta.getFieldName();
        for ( int i = 0; i < fieldName.length; i++ ) {
          if ( fieldName[i] == null || fieldName[i].length() == 0 ) {
            continue;

View on GitHub (pinned to f3058517a1)