apache/iceberg · warning

Unable to load metrics class: '{}', falling back to null met

Error message

Unable to load metrics class: '{}', falling back to null metrics

What it means

S3FileIO.initMetrics() tries to instantiate the configured metrics implementation class (default MetricsContext) reflectively. If the class is missing, has no compatible constructor, or doesn't implement MetricsContext, it logs this warning and falls back to null metrics — FileIO keeps working but metrics collection is disabled.

Source

Thrown at aws/src/main/java/org/apache/iceberg/aws/s3/S3FileIO.java:532

      }
    }

    initMetrics(properties);
  }

  @SuppressWarnings("CatchBlockLogException")
  private void initMetrics(Map<String, String> props) {
    // Report Hadoop metrics if Hadoop is available
    try {
      DynConstructors.Ctor<MetricsContext> ctor =
          DynConstructors.builder(MetricsContext.class)
              .hiddenImpl(DEFAULT_METRICS_IMPL, String.class)
              .buildChecked();
      MetricsContext context = ctor.newInstance(ROOT_PREFIX);
      context.initialize(props);
      this.metrics = context;
    } catch (NoClassDefFoundError | NoSuchMethodException | ClassCastException e) {
      LOG.warn(
          "Unable to load metrics class: '{}', falling back to null metrics", DEFAULT_METRICS_IMPL);
    }
  }

  @Override
  public void close() {
    // handles concurrent calls to close()
    if (isResourceClosed.compareAndSet(false, true)) {
      if (clientByPrefix != null) {
        clientByPrefix.values().forEach(PrefixedS3Client::close);
        this.clientByPrefix = null;
      }
      if (refreshFuture != null) {
        refreshFuture.cancel(true);
        refreshFuture = null;
      }
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Add the metrics-related dependencies to the classpath (or use the full iceberg-aws-bundle)
2. Set the metrics impl property to a class that exists and implements MetricsContext
3. Accept the fallback if metrics are not needed — this warning is harmless otherwise
4. Fix NoSuchMethodException cases by ensuring the impl has a public constructor taking a String scope name

try {
  Class.forName("org.apache.iceberg.metrics.LoggingMetricsContext");
} catch (ClassNotFoundException e) {
  // metrics dependency missing; add it or accept null metrics
}

When it happens

Trigger: initialize() called on a classpath missing the metrics dependency (e.g. iceberg-aws-bundle trimmed, micrometer/config libs absent), or a custom metrics class name configured that isn't a MetricsContext or lacks a (String) constructor.

Common situations: Shaded/thin deployment jars missing optional metrics dependencies; upgrading Iceberg where the metrics impl class moved; typo in metrics impl configuration.

Related errors

• Unable to load metrics class: '{}', falling back to null met
• Unable to load metrics class: '{}', falling back to null met
• Cannot load class %s, it does not exist in the classpath
• Cannot load class %s, it does not exist in the classpath
• Cannot find class; alternatives: ${classNames}

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/8043d332fef87e07. Report an issue: GitHub.