pentaho/pentaho-kettle · error · KettleException

Reference key ' ': reference value ' ' is not equal to

Error message

Reference key '{0}': reference value '{1}' is not equal to '{2}'

What it means

StepInjectionUtil.compareEntryValues throws this when both reference and compare values are non-null but not equal (per Object.equals). The message includes the entry key and both values so the exact divergent field can be identified.

Solutions

1. Read the key and both values from the message and align the compared transformation's setting with the reference (or vice versa).
2. Regenerate the reference snapshot if the new value is the intended baseline.
3. Check for environment-specific values (paths, hostnames) and parameterize them before comparison.

Example fix

// before
meta.setRowLimit("100"); // reference says 0
// after
meta.setRowLimit("0");

// Pre-compare leaf values to collect all mismatches up front
for (int i = 0; i < refEntries.size(); i++) {
  Object r = refEntries.get(i).getValue(), c = cmpEntries.get(i).getValue();
  if (r != null && c != null && !r.equals(c)) { mismatches.add(refEntries.get(i).getKey() + ": " + r + " != " + c); }
}

try { StepInjectionUtil.compareEntryValues(ref, cmp); } catch (KettleException e) { if (e.getMessage().contains("is not equal to")) { log.error("Metadata value divergence: " + e.getMessage()); } else { throw e; } }

When it happens

Trigger: compareEntryValues on leaf entries where refEntry.getValue() != null, cmpEntry.getValue() != null, and !ref.equals(cmp) — e.g. different filenames, row limits, or field mappings between the two metadata sets.

Common situations: Regression testing step metadata after code changes: a transformation's saved setting differs from the golden reference; or two environments were configured with different values (dev vs prod paths, ports, table names).

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Reference key ' ': value is not null while the compare…
• Reference key ' ': value is null while the compare value is…
• The number of reference entries
• : Comparing values can not be done with data type :
• TableOutputMeta.Exception.ConnectionUndefined

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/step/StepInjectionUtil.java:113

    for ( int i = 0; i < refEntries.size(); i++ ) {
      StepInjectionMetaEntry refEntry = refEntries.get( i );
      StepInjectionMetaEntry cmpEntry = cmpEntries.get( i );
      if ( cmpEntry.getValueType() == ValueMetaInteger.TYPE_NONE ) {
        compareEntryValues( refEntry.getDetails(), cmpEntry.getDetails() );
      } else {
        Object ref = refEntry.getValue();
        Object cmp = cmpEntry.getValue();
        if ( ref != null && cmp == null ) {
          throw new KettleException( "Reference key '" + refEntry.getKey()
            + "': value is not null while the compare value is null" );
        }
        if ( ref == null && cmp != null ) {
          throw new KettleException( "Reference key '" + refEntry.getKey()
            + "': value is null while the compare value is not null" );
        }
        if ( ref != null && cmp != null ) {
          if ( !ref.equals( cmp ) ) {
            throw new KettleException( "Reference key '" + refEntry.getKey()
              + "': reference value '" + ref + "' is not equal to '" + cmp + "'" );
          }
        }
      }
    }
  }
}

View on GitHub (pinned to f3058517a1)