apache/hadoop · error · MetricsException

Metric name {} already exists!

Error message

Metric name {} already exists!

What it means

The second half of checkMetricName: registering a metric name that already exists in this registry's metricsMap throws MetricsException('Metric name <name> already exists!'). Every new* factory method in MetricsRegistry enforces per-registry name uniqueness for metrics.

Source

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

  }

  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.
   */
  public synchronized void snapshot(MetricsRecordBuilder builder, boolean all) {
    for (MetricsTag tag : tags()) {
      builder.add(tag);
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Re-use the existing metric object instead of registering the name again
2. Rename the second metric so names stay unique within the registry
3. Re-create the registry on re-init rather than re-registering the same names

Example fix

// before
registry.newCounter("Files", "Files", 0L);
registry.newRate("Files", "Files");  // throws: name exists

// after
registry.newCounter("Files", "Files", 0L);
registry.newRate("FilesRate", "Files rate");

Set<String> usedNames = ConcurrentHashMap.newKeySet();
if (!usedNames.add(name)) {
  throw new IllegalStateException("metric name already registered: " + name);
}
registry.newRate(name, desc);

When it happens

Trigger: Two new* calls with the same name on the same MetricsRegistry — e.g., @Metric(name="X") on two members, or manual newRate("X") after newCounter("X").

Common situations: Copy-pasted metric declarations; a field metric and a method metric sharing a name; repeated component init writing into one shared registry.

Related errors

• Tag {} already exists!
• Unexpected metrics type {} for {}
• Unsupported add(value) for metric {}
• Metric name '{}' contains illegal whitespace character
• Illegal tag pattern: {}

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