pentaho/pentaho-kettle · error · EvaluationException

ERROR_INVALID_ARGUMENT

ERROR_INVALID_ARGUMENT

Error message

ERROR_INVALID_ARGUMENT (invalid argument for formula field lookup)

What it means

EvaluationException carrying LibFormulaErrorValue.ERROR_INVALID_ARGUMENT thrown by RowForumulaContext.resolveReference() when a formula references a name that cannot be resolved to any field in the row. The row context looks up the field by index cache, then by name via rowMeta.indexOfValue(); a negative index means the referenced field does not exist.

Solutions

Correct the field reference in the formula so it exactly matches an input field name (wrap names with spaces in brackets).
Preview the input of the Formula step to confirm available field names.
Ensure upstream steps producing the referenced field run before this step.
Use string literals for constants instead of bare names (bare names are treated as field references).

Example fix

// before
"price * qty"
// after
"[price] * [quantity]" // exact field names from the input row

Defensive patterns

Strategy: validation

Validate before calling

// before evaluating, ensure referenced names resolve
String[] names = rowMeta.getFieldNames();
// verify each referenced identifier appears in names, else fix the formula

Try / catch

try { value = formula.evaluate(); } catch (EvaluationException e) { if (e.getErrorValue() instanceof LibFormulaErrorValue) log.error("Unresolved formula reference, check field names: " + e.getMessage()); throw e; }

Prevention

Wrap field names in square brackets in formulas
Quote literal constants so they are not treated as fields
Preview the step's input rows to confirm field availability
Avoid referencing fields produced later in the stream

When it happens

Trigger: A formula expression references [field_name] that is absent from the row being evaluated — misspelled reference, field produced later in the stream, or field removed between metadata resolution and evaluation.

Common situations: Field names with special characters/typo in formula; referencing a constant by mistake without quotes; formula steps wired to a different stream than designed; renamed upstream columns.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/formula/RowForumulaContext.java:87

    return AnyType.TYPE;
  }

  /**
   * We return the content of a Value with the given name. We cache the position of the field indexes.
   *
   * @see org.jfree.formula.FormulaContext#resolveReference(java.lang.Object)
   */
  public Object resolveReference( Object name ) throws EvaluationException {
    if ( name instanceof String ) {
      ValueMetaInterface valueMeta;
      Integer idx = valueIndexMap.get( name );
      if ( idx != null ) {
        valueMeta = rowMeta.getValueMeta( idx.intValue() );
      } else {
        int index = rowMeta.indexOfValue( (String) name );
        if ( index < 0 ) {
          ErrorValue errorValue = new LibFormulaErrorValue( LibFormulaErrorValue.ERROR_INVALID_ARGUMENT );
          throw new EvaluationException( errorValue );
        }
        valueMeta = rowMeta.getValueMeta( index );
        idx = new Integer( index );
        valueIndexMap.put( (String) name, idx );
      }
      Object valueData = rowData[idx];
      try {
        return getPrimitive( valueMeta, valueData );
      } catch ( KettleValueException e ) {
        throw new EvaluationException( LibFormulaErrorValue.ERROR_ARITHMETIC_VALUE );
      }
    }
    return null;
  }

  public Configuration getConfiguration() {
    return formulaContext.getConfiguration();
  }

View on GitHub (pinned to f3058517a1)