apache/hadoop · error · IllegalArgumentException

[{0}] = [{1}] must be "{2}"

Error message

[{0}] = [{1}] must be "{2}"

What it means

Thrown by Check.validIdentifier (Check.java:131) when the string fits within maxLen but fails the identifier pattern ^[a-zA-Z_][a-zA-Z0-9_-]*$: the first character must be a letter or underscore, the rest may be letters, digits, underscores, or hyphens. The message prints the exact pattern so the offending character class is visible. Leading digits, dots, spaces, slashes, and other punctuation all trigger it.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/util/Check.java:132

   * Verifies a value is a valid identifier,
   * <code>[a-zA-Z_][a-zA-Z0-9_\-]*</code>, up to a maximum length.
   *
   * @param value string to check if it is a valid identifier.
   * @param maxLen maximun length.
   * @param name the name to use in the exception message.
   *
   * @return the value.
   *
   * @throws IllegalArgumentException if the string is not a valid identifier.
   */
  public static String validIdentifier(String value, int maxLen, String name) {
    Check.notEmpty(value, name);
    if (value.length() > maxLen) {
      throw new IllegalArgumentException(
        MessageFormat.format("[{0}] = [{1}] exceeds max len [{2}]", name, value, maxLen));
    }
    if (!IDENTIFIER_PATTERN.matcher(value).find()) {
      throw new IllegalArgumentException(
        MessageFormat.format("[{0}] = [{1}] must be \"{2}\"", name, value, IDENTIFIER_PATTERN_STR));
    }
    return value;
  }

  /**
   * Verifies an integer is greater than zero.
   *
   * @param value integer value.
   * @param name the name to use in the exception message.
   *
   * @return the value.
   *
   * @throws IllegalArgumentException if the integer is zero or less.
   */
  public static int gt0(int value, String name) {
    return (int) gt0((long) value, name);
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Fix the value to match [a-zA-Z_][a-zA-Z0-9_-]*: replace dots/spaces/slashes with '-' or '_'.
2. Trim the input before validating to strip stray whitespace or newlines from config files.
3. If dots are genuinely required, this helper is the wrong validator — use Check.notEmpty plus your own Pattern.
4. Add a regex unit test pinning the accepted character set, including a leading-digit rejection case.

Example fix

// before
Check.validIdentifier("httpfs.server.01", 39, "name"); // throws: must be "[a-zA-Z_][a-zA-Z0-9_-]*"

// after
Check.validIdentifier("httpfs-server-01", 39, "name"); // ok

private static final Pattern ID = Pattern.compile("[a-zA-Z_][a-zA-Z0-9_-]*");
String value = conf.get("service.name");
if (value != null && !ID.matcher(value).matches()) {
  throw new ConfigurationException("service.name must match " + ID.pattern() + ", got " + value);
}

static boolean isValidIdentifier(String v, int maxLen) {
  return v != null && !v.isEmpty() && v.length() <= maxLen
      && v.matches("[a-zA-Z_][a-zA-Z0-9_-]*");
}

try {
  Check.validIdentifier(value, maxLen, name);
} catch (IllegalArgumentException ex) {
  throw new ConfigurationException("Invalid config value: " + ex.getMessage(), ex);
}

When it happens

Trigger: Calls like Check.validIdentifier("1abc", ...), "svc name", "svc.name", "[a", or "`a" — the exact negative cases covered by TestCheck. Realistically: a config-derived name containing a dot (fully-qualified hostname, dotted property suffix) or stray whitespace/newline reaching the validator.

Common situations: Passing an FQDN or dotted name where a simple identifier is required; values pasted from user input with trailing newlines; encoding issues introducing invisible characters.

Related errors

• Invalid value
• [{0}] = [{1}] exceeds max len [{2}]
• parameter [{0}] = [{1}] must be greater than zero
• parameter [{0}] = [{1}] must be greater than or equals zero
• Parameter [{0}], invalid value [{1}], value must be [{2}]

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/28cb4da3bbe6b14f. Report an issue: GitHub.