apache/hadoop · error · MetricsException

Metric name '{}' contains illegal whitespace character

Error message

Metric name '{}' contains illegal whitespace character

What it means

MetricsRegistry.checkMetricName runs before every registration and rejects any name containing a whitespace character (Character.isWhitespace), throwing MetricsException("Metric name '<name>' contains illegal whitespace character") even before the duplicate check runs.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/lib/MetricsRegistry.java:445

    return tagsMap.values();
  }

  Collection<MutableMetric> metrics() {
    return metricsMap.values();
  }

  private void checkMetricName(String name) {
    // Check for invalid characters in metric name
    boolean foundWhitespace = false;
    for (int i = 0; i < name.length(); i++) {
      char c = name.charAt(i);
      if (Character.isWhitespace(c)) {
        foundWhitespace = true;
        break;
      }
    }
    if (foundWhitespace) {
      throw new MetricsException("Metric name '"+ name +
          "' contains illegal whitespace character");
    }
    // Check if name has already been registered
    if (metricsMap.containsKey(name)) {
      throw new MetricsException("Metric name "+ name +" already exists!");
    }
  }

  private void checkTagName(String name) {
    if (tagsMap.containsKey(name)) {
      throw new MetricsException("Tag "+ name +" already exists!");
    }
  }

  /**
   * Sample all the mutable metrics and put the snapshot in the builder
   * @param builder to contain the metrics snapshot
   * @param all get all the metrics even if the values are not changed.

View on GitHub (pinned to 2add963021)

Solutions

Strip or replace whitespace from the name before registering it
Use camelCase identifiers for names and put the pretty label in the description
Sanitize config-sourced metric names once at startup

Example fix

// before
registry.newRate("Num Ops", "Number of operations");

// after
registry.newRate("NumOps", "Number of operations");

Defensive patterns

Strategy: validation

Validate before calling

static String sanitizeMetricName(String name) {
  return name == null ? null : name.replaceAll("\\s+", "");
}
// before every registration:
String safe = sanitizeMetricName(name);
if (!safe.equals(name)) throw new IllegalArgumentException("whitespace in metric name: " + name);

Type guard

static boolean isValidMetricName(String name) {
  return name != null && !name.isEmpty() && name.chars().noneMatch(Character::isWhitespace);
}

Prevention

Use camelCase identifiers as metric names and put pretty labels in descriptions
Sanitize config-sourced names once at startup
Assert isValidMetricName in tests for every registry factory call

When it happens

Trigger: Any registry factory call (newCounter, newGauge, newRate, newQuantiles, ...) with a name containing a space, tab, or newline — e.g., newRate("Num Ops").

Common situations: Human-readable labels pasted in as metric names; names built by string concatenation that accidentally include spaces; config-provided names with leading/trailing whitespace.

Related errors

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