pentaho/pentaho-kettle · error · IllegalArgumentException

Key must not start with '-'

Error message

Key must not start with '-'

What it means

KeyValue.assertKey() rejects keys that begin with '-' to prevent them from being mistaken for command-line flags or negative-prefixed identifiers. A leading hyphen triggers IllegalArgumentException('Key must not start with \'-\'').

Solutions

1. Strip leading '-' characters from the key before creating the KeyValue.
2. Rename the key without the leading hyphen (e.g. 'verbose' instead of '-verbose').
3. Apply the same lowercase/replace sanitize step used for invalid characters, trimming leading hyphens first.

Example fix

// before
new KeyValue<>("-verbose", true);
// after
String key = "-verbose".replaceAll("^-+", "");
new KeyValue<>(key, true); // "verbose"

if (key.startsWith("-")) {
  throw new IllegalArgumentException("Key must not start with '-': " + key);
}

try {
  new KeyValue<>(key, value);
} catch (IllegalArgumentException e) {
  key = key.replaceAll("^-+", ""); // strip and retry once
}

When it happens

Trigger: Constructing a KeyValue (or calling assertKey) with a key like '-verbose' or '--force', e.g. when mapping CLI flag names directly to keys.

Common situations: Developers reusing CLI option names as key names; string manipulations that leave a leading dash after sanitizing.

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.

Related errors

• Key contains invalid characters
• Key must not be '_'
• Key must not end 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/a8054132d1f994fc. Report an issue: GitHub.

Appendix: source

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

   */
  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;
  }

  /**
   * @return the value

View on GitHub (pinned to f3058517a1)