{"record":{"id":"dc567bb144fccf56","repo":"apache/iceberg","slug":"unable-to-load-metrics-class-falling-back-t","errorCode":null,"errorMessage":"Unable to load metrics class: '{}', falling back to null metrics","messagePattern":"Unable to load metrics class: '(.+?)', falling back to null metrics","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"aliyun/src/main/java/org/apache/iceberg/aliyun/oss/OSSFileIO.java","lineNumber":122,"sourceCode":"  }\n\n  @Override\n  public void initialize(Map<String, String> properties) {\n    AliyunClientFactory factory = AliyunClientFactories.from(properties);\n    this.aliyunProperties = factory.aliyunProperties();\n    this.oss = factory::newOSSClient;\n\n    // Report Hadoop metrics if Hadoop is available\n    try {\n      DynConstructors.Ctor<MetricsContext> ctor =\n          DynConstructors.builder(MetricsContext.class)\n              .hiddenImpl(DEFAULT_METRICS_IMPL, String.class)\n              .buildChecked();\n      MetricsContext context = ctor.newInstance(\"oss\");\n      context.initialize(properties);\n      this.metrics = context;\n    } catch (NoClassDefFoundError | NoSuchMethodException | ClassCastException e) {\n      LOG.warn(\n          \"Unable to load metrics class: '{}', falling back to null metrics\",\n          DEFAULT_METRICS_IMPL,\n          e);\n    }\n  }\n\n  @Override\n  public void close() {\n    // handles concurrent calls to close()\n    if (isResourceClosed.compareAndSet(false, true)) {\n      if (client != null) {\n        client.shutdown();\n      }\n    }\n  }\n}\n","sourceCodeStart":104,"sourceCodeEnd":139,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/aliyun/src/main/java/org/apache/iceberg/aliyun/oss/OSSFileIO.java#L104-L139","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add/align the aliyun-sdk-oss dependency version matching the Iceberg release (check iceberg-aliyun's declared dependency).","Verify the jar with the OSS metrics classes is shipped to the cluster (no 'provided' scope in the deployed jar).","Ignore the warning if metrics reporting is not needed — the FileIO functions normally with null metrics.","Upgrade the Iceberg aliyun module so it matches your SDK version's metrics API."],"exampleFix":"// before (build.gradle)\nimplementation 'com.aliyun.oss:aliyun-sdk-oss:2.8.3'\n// after\nimplementation 'com.aliyun.oss:aliyun-sdk-oss:3.17.4' // version matching iceberg-aliyun","handlingStrategy":"fallback","validationCode":"boolean hasOssMetrics;\ntry {\n  Class.forName(\"com.aliyun.oss.common.comm.MetricsReporter\");\n  hasOssMetrics = true;\n} catch (ClassNotFoundException | NoClassDefFoundError e) {\n  hasOssMetrics = false;\n}\nif (!hasOssMetrics) LOG.info(\"aliyun-sdk-oss metrics classes absent; OSS metrics will be disabled\");","typeGuard":null,"tryCatchPattern":"try {\n  fileIO.initialize(props);\n} catch (Exception e) {\n  // OSSFileIO itself degrades gracefully; only handle truly fatal init here\n  throw e;\n}","preventionTips":["Pin aliyun-sdk-oss to the version declared by your Iceberg release.","Verify with ./gradlew dependencies that iceberg-aliyun's SDK dependency is not overridden.","Ship the full iceberg-aliyun runtime jar (plus SDK) to the cluster, not a 'provided'-scoped build.","Decide whether OSS metrics matter; if not, the warning can be safely ignored."],"tags":["aliyun","oss","reflection","classpath","metrics"],"backgroundTag":"class-not-found","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}