What causes "SymmetricCryptoTrans.Exception.SecretKeyFieldMissing" in pentaho/pentaho-kettle?

In the step dialog select the secret key field name from the incoming fields.

pentaho/pentaho-kettle · error · KettleStepException

SymmetricCryptoTrans.Exception.SecretKeyFieldMissing

SymmetricCryptoTrans.Exception.SecretKeyFieldMissing

Error message

SymmetricCryptoTrans.Exception.SecretKeyFieldMissing

What it means

When the secret key is read dynamically from the data stream (secretKeyInField = true), the step requires a secret key field name. processRow throws this KettleStepException when meta.getSecretKeyField() is empty, because it cannot know which incoming column holds the per-row key.

Solutions

In the step dialog select the secret key field name from the incoming fields.
Programmatically call meta.setSecretKeyField("keyColumn") when secretKeyInField is true.
Alternatively disable 'secret key in field' and provide a static key, which bypasses this check.

Example fix

// before
meta.setSecretKeyInField(true); // no key field set
// after
meta.setSecretKeyInField(true);
meta.setSecretKeyField("secret_key");

Defensive patterns

Strategy: validation

Validate before calling

if (meta.isSecretKeyInField()
    && (meta.getSecretKeyField() == null || meta.getSecretKeyField().isEmpty())) {
  throw new IllegalArgumentException(
    "secretKeyInField=true requires a secret key field name");
}

Try / catch

try {
  trans.execute(null);
} catch (KettleStepException e) {
  if (e.getMessage().contains("SecretKeyFieldMissing")) {
    logError("Set the secret key field name or switch to a static key");
  }
}

Prevention

Whenever enabling 'secret key in field', immediately set the key field name.
Run meta.check() before saving/executing to catch missing configuration.
Keep static-key and field-key modes clearly separated in your metadata builders.

When it happens

Trigger: 'secret key in field' is enabled (or isSecretKeyInField() returns true from a loaded/legacy configuration) but the 'Secret key fieldname' option is empty in the step metadata.

Common situations: Programmatic construction where setSecretKeyInField(true) was called without setSecretKeyField(); metadata migration flipping the flag without updating the field; hand-edited transformation XML enabling secretKeyInField='Y' with no secretKeyField tag.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/symmetriccrypto/symmetriccryptotrans/SymmetricCryptoTrans.java:109

        throw new KettleStepException( BaseMessages.getString(
          PKG, "SymmetricCryptoTrans.Exception.CouldnotFindField", meta.getMessageFied() ) );
      }

      if ( !meta.isSecretKeyInField() ) {
        String realSecretKey =
          Encr.decryptPasswordOptionallyEncrypted( environmentSubstitute( meta.getSecretKey() ) );
        if ( Utils.isEmpty( realSecretKey ) ) {
          throw new KettleStepException( BaseMessages.getString(
            PKG, "SymmetricCryptoTrans.Exception.SecretKeyMissing" ) );
        }
        // We have a static secret key
        // Set secrete key
        setSecretKey( realSecretKey );

      } else {
        // dynamic secret key
        if ( Utils.isEmpty( meta.getSecretKeyField() ) ) {
          throw new KettleStepException( BaseMessages.getString(
            PKG, "SymmetricCryptoTrans.Exception.SecretKeyFieldMissing" ) );
        }
        // Try to get secret key field index
        data.indexOfSecretkeyField = getInputRowMeta().indexOfValue( meta.getSecretKeyField() );

        // Let's check the Field
        if ( data.indexOfSecretkeyField < 0 ) {
          // The field is unreachable !
          throw new KettleStepException( BaseMessages.getString(
            PKG, "SymmetricCryptoTrans.Exception.CouldnotFindField", meta.getSecretKeyField() ) );
        }
      }

    }

    try {

      // handle dynamic secret key

View on GitHub (pinned to f3058517a1)