{"record":{"id":"c59edca20326cf57","repo":"apache/iceberg","slug":"cannot-initialize-catalog-implementation-s-s","errorCode":null,"errorMessage":"Cannot initialize Catalog implementation %s: %s","messagePattern":"Cannot initialize Catalog implementation (.+?): (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/CatalogUtil.java","lineNumber":279,"sourceCode":"   * <p>The catalog must have a no-arg constructor. If the class implements Configurable, a Hadoop\n   * config will be passed using Configurable.setConf. {@link Catalog#initialize(String catalogName,\n   * Map options)} is called to complete the initialization.\n   *\n   * @param impl catalog implementation full class name\n   * @param catalogName catalog name\n   * @param properties catalog properties\n   * @param hadoopConf hadoop configuration if needed\n   * @return initialized catalog object\n   * @throws IllegalArgumentException if no-arg constructor not found or error during initialization\n   */\n  public static Catalog loadCatalog(\n      String impl, String catalogName, Map<String, String> properties, Object hadoopConf) {\n    Preconditions.checkNotNull(impl, \"Cannot initialize custom Catalog, impl class name is null\");\n    DynConstructors.Ctor<Catalog> ctor;\n    try {\n      ctor = DynConstructors.builder(Catalog.class).impl(impl).buildChecked();\n    } catch (NoSuchMethodException e) {\n      throw new IllegalArgumentException(\n          String.format(\"Cannot initialize Catalog implementation %s: %s\", impl, e.getMessage()),\n          e);\n    }\n\n    Catalog catalog;\n    try {\n      catalog = ctor.newInstance();\n\n    } catch (ClassCastException e) {\n      throw new IllegalArgumentException(\n          String.format(\"Cannot initialize Catalog, %s does not implement Catalog.\", impl), e);\n    }\n\n    configureHadoopConf(catalog, hadoopConf);\n\n    catalog.initialize(catalogName, properties);\n    return catalog;\n  }","sourceCodeStart":261,"sourceCodeEnd":297,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/CatalogUtil.java#L261-L297","documentation":"Thrown by CatalogUtil.loadCatalog when the given catalog implementation class name cannot be resolved to a class with a usable no-arg constructor (the class is not on the classpath or has no suitable constructor). DynConstructors.buildChecked() raises NoSuchMethodException, which is wrapped in this IllegalArgumentException with the original cause attached.","triggerScenarios":"Calling CatalogUtil.loadCatalog(impl, name, properties, hadoopConf) or buildIcebergCatalog with a catalog-impl property naming a class that is missing from the runtime classpath, misspelled, not public, or lacking a public no-arg constructor.","commonSituations":"Typos in io.catalog-impl / catalog-impl config; the connector JAR (e.g. iceberg-aws, iceberg-nessie) not on the classpath of Spark/Flink/Trino; using a fully qualified class name from a different Iceberg major version that was renamed or moved; shading/relocation breaking reflection.","solutions":["Verify the class name in the catalog-impl property is spelled correctly and fully qualified (e.g. org.apache.iceberg.rest.RESTCatalog).","Add the Iceberg runtime/connector JAR containing the class to the application classpath (e.g. iceberg-aws-bundle, iceberg-gcp-bundle, iceberg-nessie).","Check that the class is public and declares a public no-arg constructor; add one or use a different implementation.","Confirm the Iceberg version of the runtime JARs matches the version the class name was written for (classes move between versions)."],"exampleFix":"// before\nMap<String, String> opts = Map.of(\"type\", \"jdbc\"); // JAR missing -> NoSuchMethodException for JDBC catalog\n// after\n// add iceberg-jdbc (or the bundle jar) to the classpath, or use an available type:\nMap<String, String> opts = Map.of(\"type\", \"hadoop\");","handlingStrategy":"try-catch","validationCode":"try {\n  Class<?> cls = Class.forName(implClassName, true, Thread.currentThread().getContextClassLoader());\n  if (!org.apache.iceberg.Catalog.class.isAssignableFrom(cls) || cls.getConstructor() == null) {\n    throw new IllegalStateException(implClassName + \" missing or lacks public no-arg constructor\");\n  }\n} catch (ClassNotFoundException e) {\n  throw new IllegalStateException(\"Catalog class not on classpath: \" + implClassName, e);\n}","typeGuard":"static boolean isLoadableCatalog(String impl) {\n  try {\n    Class<?> cls = Class.forName(impl);\n    return Catalog.class.isAssignableFrom(cls);\n  } catch (ClassNotFoundException | NoClassDefFoundError e) {\n    return false;\n  }\n}","tryCatchPattern":"try {\n  Catalog catalog = CatalogUtil.loadCatalog(impl, name, props, hadoopConf);\n} catch (IllegalArgumentException e) {\n  LOG.error(\"Failed to load catalog impl {} (check classpath/bundle jars): {}\", impl, e.getMessage(), e);\n  throw e; // config error is not recoverable\n}","preventionTips":["Always ship the matching Iceberg bundle/runtime JAR with your application.","Use well-known built-in type values (rest, hive, hadoop, glue, nessie, jdbc, bigquery) instead of raw class names when possible.","Keep a single Iceberg version on the classpath; avoid shaded duplicates.","Unit-test catalog loading at startup with a smoke test that calls CatalogUtil.loadCatalog."],"tags":["reflection","classpath","catalog","initialization"],"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"}