pentaho/pentaho-kettle · error · KettleException

Rest.Exception.MatrixParamFieldEmpty

Rest.Exception.MatrixParamFieldEmpty

Error message

Rest.Exception.MatrixParamFieldEmpty

What it means

Thrown by calcParameters() when a matrix parameter entry has an empty field name configured. The REST step iterates the matrix parameter fields; if one is blank (Utils.isEmpty), it cannot build the request, so it fails fast with this message.

Solutions

  1. Open the REST step dialog and fill in the Field column for every matrix parameter row
  2. Remove unused/blank matrix parameter rows
  3. Verify environment variables used for the field resolve to non-empty values

Example fix

// before
matrixParameterName = "lang"; matrixParameterField = "";
// after
matrixParameterName = "lang"; matrixParameterField = "language";
Defensive patterns

Strategy: validation

Validate before calling

for (int i = 0; i < matrixParameterFields.length; i++) {
  if (matrixParameterFields[i] == null || matrixParameterFields[i].trim().isEmpty()) {
    throw new KettleException("Matrix parameter field empty at index " + i);
  }
}

Try / catch

try { calcParameters(); } catch (KettleException e) {
  logError("Matrix parameter config invalid: " + e.getMessage());
  setErrors(1);
}

Prevention

When it happens

Trigger: A row in the Matrix parameters tab of the REST step dialog has a name but an empty field, or an environment substitution resolves to an empty string.

Common situations: User added a matrix parameter name but forgot to set the field; variable like ${EMPTY} resolves to empty; dialog copy-paste left field blank.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at plugins/rest/core/src/main/java/org/pentaho/di/trans/steps/rest/Rest.java:575

        }
        data.indexOfParamFields[ i ] = data.inputRowMeta.indexOfValue( field );
        if ( data.indexOfParamFields[ i ] < 0 ) {
          throw new KettleException( BaseMessages.getString( PKG, "Rest.Exception.ErrorFindingField", field ) );
        }
      }
      data.useParams = true;
    }

    int nrMatrixParams = meta.getMatrixParameterField() == null ? 0 : meta.getMatrixParameterField().length;
    if ( nrMatrixParams > 0 ) {
      data.nrMatrixParams = nrMatrixParams;
      data.matrixParamNames = new String[ nrMatrixParams ];
      data.indexOfMatrixParamFields = new int[ nrMatrixParams ];
      for ( int i = 0; i < nrMatrixParams; i++ ) {
        data.matrixParamNames[ i ] = environmentSubstitute( meta.getMatrixParameterName()[ i ] );
        String field = environmentSubstitute( meta.getMatrixParameterField()[ i ] );
        if ( Utils.isEmpty( field ) ) {
          throw new KettleException( BaseMessages.getString( PKG, "Rest.Exception.MatrixParamFieldEmpty" ) );
        }
        data.indexOfMatrixParamFields[ i ] = data.inputRowMeta.indexOfValue( field );
        if ( data.indexOfMatrixParamFields[ i ] < 0 ) {
          throw new KettleException( BaseMessages.getString( PKG, "Rest.Exception.ErrorFindingField", field ) );
        }
      }
      data.useMatrixParams = true;
    }
  }

  /**
   * Calculate body
   *
   * @throws KettleException
   */
  private void calcBody() throws KettleException {
    String field = environmentSubstitute( meta.getBodyField() );
    if ( !Utils.isEmpty( field ) ) {

View on GitHub (pinned to f3058517a1)