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

Enter the secret key directly in the step dialog's 'Secret key' field, or

pentaho/pentaho-kettle · error · KettleStepException

SymmetricCryptoTrans.Exception.SecretKeyMissing

SymmetricCryptoTrans.Exception.SecretKeyMissing

Error message

SymmetricCryptoTrans.Exception.SecretKeyMissing

What it means

When the secret key is supplied statically (secretKeyInField = false), the step decrypts/interpolates meta.getSecretKey() via Encr.decryptPasswordOptionallyEncrypted(environmentSubstitute(...)) and throws this KettleStepException if the resulting key is empty. Without a key the crypto operation is impossible, so the step fails at startup.

Solutions

Enter the secret key directly in the step dialog's 'Secret key' field, or
Define the referenced Kettle/environment variable (e.g. -DSECRET_KEY=... or via kettle.properties / setEnvironmentVariable) before running.
Check for typos in the ${VAR} placeholder — an unresolved-but-present variable that resolves empty still triggers this.
If the key should come from the data stream instead, enable 'secret key in field' and set the key field.

Example fix

// before
meta.setSecretKey("${SYMM_KEY}"); // SYMM_KEY not defined at runtime
// after
transMeta.setVariable("SYMM_KEY", System.getenv("SYMM_KEY"));
meta.setSecretKey("${SYMM_KEY}");

Defensive patterns

Strategy: validation

Validate before calling

String key = transMeta.getVariable("SYMM_KEY");
if (key == null || key.isEmpty()) {
  throw new IllegalStateException("Secret key variable SYMM_KEY is not set");
}

Try / catch

try {
  trans.execute(null);
} catch (KettleStepException e) {
  if (e.getMessage().contains("SecretKeyMissing")) {
    logError("Provide the secret key or define the referenced variable");
  }
}

Prevention

Define key variables in kettle.properties or pass them as transformation parameters.
Never leave the static key box empty when not using a key field.
Document required environment variables for deployments.

When it happens

Trigger: Static key mode selected but the 'Secret key' box is empty; the key references an environment variable/Kettle variable that is undefined or empty at runtime, so environmentSubstitute() resolves to an empty string.

Common situations: Deploying a transformation to a server where ${SECRET_KEY} or an internal Kettle variable isn't defined; user typed the key in one environment but used variables; key cleared accidentally in the dialog.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

        // Message Field is missing !
        throw new KettleStepException( BaseMessages.getString(
          PKG, "SymmetricCryptoTrans.Exception.MissingMessageField" ) );
      }
      // Try to get Field index
      data.indexOfMessage = getInputRowMeta().indexOfValue( meta.getMessageFied() );

      // Let's check the Field
      if ( data.indexOfMessage < 0 ) {
        // The field is unreachable !
        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 !

View on GitHub (pinned to f3058517a1)