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

OSSFileIO optionally loads a MetricsContext implementation (aliyun-sdk-oss's OssMetricsReporter/default metrics class) reflectively via ReflectionUtil. If the class is missing, has no compatible constructor, cannot be cast, or is not on the classpath (NoClassDefFoundError), OSSFileIO logs a warning and leaves this.metrics null so all operations proceed without OSS metrics reporting. It is a graceful degradation, not a failure.

Source

Thrown at aliyun/src/main/java/org/apache/iceberg/aliyun/oss/OSSFileIO.java:122

  }

  @Override
  public void initialize(Map<String, String> properties) {
    AliyunClientFactory factory = AliyunClientFactories.from(properties);
    this.aliyunProperties = factory.aliyunProperties();
    this.oss = factory::newOSSClient;

    // 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("oss");
      context.initialize(properties);
      this.metrics = context;
    } catch (NoClassDefFoundError | NoSuchMethodException | ClassCastException e) {
      LOG.warn(
          "Unable to load metrics class: '{}', falling back to null metrics",
          DEFAULT_METRICS_IMPL,
          e);
    }
  }

  @Override
  public void close() {
    // handles concurrent calls to close()
    if (isResourceClosed.compareAndSet(false, true)) {
      if (client != null) {
        client.shutdown();
      }
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Add/align the aliyun-sdk-oss dependency version matching the Iceberg release (check iceberg-aliyun's declared dependency).
2. Verify the jar with the OSS metrics classes is shipped to the cluster (no 'provided' scope in the deployed jar).
3. Ignore the warning if metrics reporting is not needed — the FileIO functions normally with null metrics.
4. Upgrade the Iceberg aliyun module so it matches your SDK version's metrics API.

Example fix

// before (build.gradle)
implementation 'com.aliyun.oss:aliyun-sdk-oss:2.8.3'
// after
implementation 'com.aliyun.oss:aliyun-sdk-oss:3.17.4' // version matching iceberg-aliyun

boolean hasOssMetrics;
try {
  Class.forName("com.aliyun.oss.common.comm.MetricsReporter");
  hasOssMetrics = true;
} catch (ClassNotFoundException | NoClassDefFoundError e) {
  hasOssMetrics = false;
}
if (!hasOssMetrics) LOG.info("aliyun-sdk-oss metrics classes absent; OSS metrics will be disabled");

try {
  fileIO.initialize(props);
} catch (Exception e) {
  // OSSFileIO itself degrades gracefully; only handle truly fatal init here
  throw e;
}

When it happens

Trigger: FileIO.initialize(properties) on OSSFileIO when the aliyun-sdk-oss metrics classes are absent from the classpath or changed across SDK versions (constructor signature mismatch), during table refresh via SerializableTable/FileIO initialization in any engine.

Common situations: Using iceberg-aliyun with a different aliyun-sdk-oss version than the one Iceberg was built against; shaded/provided-scope SDK in a Spark/Flink cluster; uber-jar shading dropping aliyun metrics classes.

Related errors

• Unable to load metrics class: '{}', falling back to null met
• Unable to load metrics class: '{}', falling back to null met
• Cannot initialize AliyunClientFactory, missing no-arg constr
• Cannot initialize AliyunClientFactory, %s does not implement
• Failed to create RRSA OSS client

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