apache/hadoop · error · IllegalArgumentException

[{0}] = [{1}] exceeds max len [{2}]

Error message

[{0}] = [{1}] exceeds max len [{2}]

What it means

Thrown by the Hadoop httpfs library's precondition helper Check.validIdentifier(value, maxLen, name) (hadoop-hdfs-httpfs, org.apache.hadoop.lib.util.Check:127) when a string passes the null/empty check but is longer than the caller-declared maxLen. The helper validates identifier-shaped values against [a-zA-Z_][a-zA-Z0-9_-]* with a length cap, and the message reports the parameter name, the offending value, and the limit. It is a plain IllegalArgumentException, so it aborts whatever startup or construction path was validating the value.

Source

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

  private static final Pattern IDENTIFIER_PATTERN = Pattern.compile("^" + IDENTIFIER_PATTERN_STR + "$");

  /**
   * 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.

View on GitHub (pinned to 2add963021)

Solutions

1. Shorten the value to at most maxLen characters (rename the service/instance in the config).
2. If the longer value is legitimate, raise the maxLen argument at the call site so the contract matches reality.
3. Sanitize the input before validation: trim whitespace and drop verbose segments (prefixes, domains).
4. Add boundary unit tests: length == maxLen passes, maxLen + 1 throws.

Example fix

// before
String serviceName = conf.get("service.name", "filesystem-server-01");
Check.validIdentifier(serviceName, 10, "service.name"); // throws: exceeds max len [10]

// after
String serviceName = conf.get("service.name", "fssvc01");
Check.validIdentifier(serviceName, 10, "service.name"); // ok

String value = conf.get("service.name");
int maxLen = 10;
if (value == null || value.isEmpty()) throw new ConfigurationException("service.name is required");
if (value.length() > maxLen) throw new ConfigurationException("service.name must be <= " + maxLen + " chars: " + 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) {
  // config error: fail fast with the offending property name
  throw new ConfigurationException("Invalid config value: " + ex.getMessage(), ex);
}

When it happens

Trigger: Any call Check.validIdentifier(v, maxLen, name) where v.length() > maxLen, e.g. validIdentifier("filesystem-server-01", 10, "name") (18 chars vs cap 10). In practice this hits embedders of the org.apache.hadoop.lib server/webapp framework validating config-derived identifiers (service or instance names) against a small hardcoded cap.

Common situations: A config-supplied service/instance name grows past the limit after a rename; a fully-qualified hostname is passed where a short identifier was expected; a maxLen copied from another call site that validates a different, shorter field.

Related errors

• [{0}] = [{1}] must be "{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}]
• Invalid value

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