{"record":{"id":"e2a7731f4d1b51b9","repo":"apache/iceberg","slug":"unable-to-load-metrics-class-falling-back-t-e2a773","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":"gcp/src/main/java/org/apache/iceberg/gcp/gcs/GCSFileIO.java","lineNumber":181,"sourceCode":"  @Override\n  public void initialize(Map<String, String> props) {\n    this.properties = SerializableMap.copyOf(props);\n    initMetrics(properties);\n  }\n\n  @SuppressWarnings(\"CatchBlockLogException\")\n  private void initMetrics(Map<String, String> props) {\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(\"gcs\");\n      context.initialize(props);\n      this.metrics = context;\n    } catch (NoClassDefFoundError | NoSuchMethodException | ClassCastException e) {\n      LOG.warn(\n          \"Unable to load metrics class: '{}', falling back to null metrics\", DEFAULT_METRICS_IMPL);\n    }\n  }\n\n  private Map<String, PrefixedStorage> storageByPrefix() {\n    if (null == storageByPrefix) {\n      synchronized (this) {\n        if (null == storageByPrefix) {\n          Map<String, PrefixedStorage> localStorageByPrefix = Maps.newHashMap();\n\n          localStorageByPrefix.put(\n              ROOT_STORAGE_PREFIX,\n              new PrefixedStorage(ROOT_STORAGE_PREFIX, properties, storageSupplier));\n          storageCredentials.stream()\n              .filter(c -> c.prefix().startsWith(ROOT_STORAGE_PREFIX))\n              .collect(Collectors.toList())\n              .forEach(\n                  storageCredential -> {","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/gcp/src/main/java/org/apache/iceberg/gcp/gcs/GCSFileIO.java#L163-L199","documentation":"GCSFileIO.initMetrics attempts to reflectively instantiate the default GCS metrics implementation class. If that class cannot be loaded/constructed (missing dependency, wrong signature, or ClassCastException), the FileIO logs a warning and falls back to null metrics — the catalog still works but GCS request metrics are not collected.","triggerScenarios":"Calling GCSFileIO.initialize(...) when the metrics class (gcs-metrics module, e.g. showcasing opencensus/opentelemetry deps) is not on the classpath, its constructor signature changed, or it does not implement MetricsContext.","commonSituations":"Using iceberg-gcp without the gcp-bundle/shaded jar; depending only on iceberg-gcp core and missing the optional metrics dependency; upgrading Iceberg where DEFAULT_METRICS_IMPL class moved.","solutions":["Add the GCS metrics dependency (org.apache.iceberg:iceberg-gcp-bundle or the module providing the metrics impl) to the classpath","Check the class named by DEFAULT_METRICS_IMPL exists with the expected (String) constructor","If metrics are not needed, ignore the warning — behavior is otherwise unaffected","Align Iceberg versions so iceberg-gcp and the metrics module match"],"exampleFix":"// before (Maven)\n<dependency>org.apache.iceberg:iceberg-gcp</dependency>\n// after\n<dependency>org.apache.iceberg:iceberg-gcp</dependency>\n<dependency>org.apache.iceberg:iceberg-gcp-bundle</dependency> <!-- provides metrics impl -->","handlingStrategy":"fallback","validationCode":"try { Class.forName(\"org.apache.iceberg.gcp.gcs.GcsMetricsContext\"); } catch (ClassNotFoundException e) { /* add metrics dep */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ship iceberg-gcp-bundle (shaded) to include optional metrics classes","Keep Iceberg module versions aligned","Verify with Class.forName in startup checks if metrics matter","Ignore warning if metrics are intentionally disabled"],"tags":["gcs","metrics","reflection","classpath","fallback"],"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"}