pentaho/pentaho-kettle · error · IllegalArgumentException

Key contains invalid characters

Error message

Key contains invalid characters [validKeyCharacters=${VALID_KEY_CHARS}]

What it means

KeyValue.assertKey() validates that a key is non-empty and consists only of VALID_KEY_CHARS (lowercase alphanumerics, underscore, hyphen). If StringUtils.containsOnly fails, it throws IllegalArgumentException with the list of valid characters. This keeps keys usable in environments like env-var/CLI/JSON contexts.

Solutions

1. Sanitize the key to lowercase and replace invalid characters with '-' or '_' before constructing the KeyValue.
2. Use only [a-z0-9_-] characters in keys.
3. Call KeyValue.assertKey(key) proactively in your own code to fail early with your own message.

Example fix

// before
new KeyValue<>("Max Retries", 3);
// after
String key = "Max Retries".toLowerCase().replaceAll("[^a-z0-9_-]", "-");
new KeyValue<>(key, 3); // "max-retries"

if (key == null || key.isEmpty() || !key.matches("[a-z0-9_-]+")) {
  throw new IllegalArgumentException("Invalid key: " + key);
}

try {
  KeyValue.assertKey(key);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Sanitize key before use: '" + key + "'", e);
}

When it happens

Trigger: Calling new KeyValue<>(key, value) (or assertKey directly) with a key containing spaces, uppercase letters, dots, slashes, or other characters outside the allowed set.

Common situations: Passing human-readable labels as keys ('Max Retries'); keys copied from config files with dots ('a.b.c'); camelCase keys not lowercased before validation.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Key must not be '_'
• Key must not end with '-'
• Key must not start with '-'
• Destination must be a folder / invalid drag-drop source…
• Key already added [key= ]

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/core/util/KeyValue.java:89

   * @param key
   *          key to set.
   * @throws IllegalArgumentException
   *           if key is invalid.
   */
  public KeyValue( final String key ) throws IllegalArgumentException {
    this( key, null );
  }

  /**
   * @param lowerKey
   *          key to test.
   * @throws IllegalArgumentException
   *           if key is invalid.
   */
  public static final void assertKey( final String lowerKey ) throws IllegalArgumentException {
    Assert.assertNotEmpty( lowerKey, "Key cannot be null or empty" );
    if ( !StringUtils.containsOnly( lowerKey, VALID_KEY_CHARS ) ) {
      throw new IllegalArgumentException( "Key contains invalid characters [validKeyCharacters="
        + VALID_KEY_CHARS + "]" );
    }
    if ( lowerKey.charAt( 0 ) == '-' ) {
      throw new IllegalArgumentException( "Key must not start with '-'" );
    }
    if ( lowerKey.endsWith( "-" ) ) {
      throw new IllegalArgumentException( "Key must not end with '-'" );
    }
    if ( "_".equals( lowerKey ) ) {
      throw new IllegalArgumentException( "Key must not be  '_'" );
    }
  }

  /**
   * @return the key, never null.
   */
  public String getKey() {
    return this.key;

View on GitHub (pinned to f3058517a1)