pentaho/pentaho-kettle · error · KettleException

Reference key ' ': value is null while the compare value is…

Error message

Reference key '{0}': value is null while the compare value is not null

What it means

The mirror case of the null-vs-not-null check in StepInjectionUtil.compareEntryValues: the reference entry's value is null while the compare entry carries a value. The compared metadata contains a setting the reference does not have, so the trees differ and a KettleException is thrown.

Solutions

1. Clear the extra value in the compared transformation for the key named in the message.
2. Update the reference snapshot if the new value is intended.
3. Verify both sides use the same plugin version so defaults match.

Example fix

// before
compareEntryValues(ref, modifiedMetaEntries); // modifiedMeta has extra value
// after
modifiedMeta.deleteExtraSetting(key); compareEntryValues(ref, modifiedMeta.getStepInjectionMetadataEntries());

// Pre-check for unexpected values on the compare side
for (int i = 0; i < refEntries.size(); i++) {
  StepInjectionMetaEntry r = refEntries.get(i), c = cmpEntries.get(i);
  if (c.getValueType() != ValueMetaInterface.TYPE_NONE && r.getValue() == null && c.getValue() != null) {
    log.warn("Unexpected compare value for key " + r.getKey());
  }
}

try { StepInjectionUtil.compareEntryValues(ref, cmp); } catch (KettleException e) { if (e.getMessage().contains("value is null while the compare value is not null")) { log.error("Compared transformation has an extra value: " + e.getMessage()); } else { throw e; } }

When it happens

Trigger: compareEntryValues on leaf entries where refEntry.getValue() == null but cmpEntry.getValue() != null for the same key.

Common situations: The compare transformation has an extra/overridden setting (e.g. a default changed, or a user set a value the reference snapshot left empty), or plugin defaults changed between versions.

Related errors

• Reference key ' ': value is not null while the compare…
• Reference key ' ': reference value ' ' is not equal to
• The number of reference entries
• AddSequence.Exception.CouldNotFindNextValueForSequence
• API error. ValueMetaInterface can't be null!

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

Appendix: source

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

    if ( refEntries.size() != cmpEntries.size() ) {
      throw new KettleException( "The number of reference entries (" + refEntries.size()
        + ") is not the same as the number of compare entries(" + cmpEntries.size() + ")" );
    }

    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)