{"record":{"id":"420b7d56f73d4106","repo":"apache/iceberg","slug":"cannot-find-class-alternatives-classnames","errorCode":null,"errorMessage":"Cannot find class; alternatives: ${classNames}","messagePattern":"Cannot find class; alternatives: (.+?)","errorType":"exception","errorClass":"ClassNotFoundException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/org/apache/iceberg/common/DynClasses.java","lineNumber":104,"sourceCode":"     *\n     * @return this Builder for method chaining\n     */\n    public Builder orNull() {\n      this.nullOk = true;\n      return this;\n    }\n\n    /**\n     * Returns the first implementation or throws ClassNotFoundException if one was not found.\n     *\n     * @param <S> Java superclass\n     * @return a {@link Class} for the first implementation found\n     * @throws ClassNotFoundException if no implementation was found\n     */\n    @SuppressWarnings(\"unchecked\")\n    public <S> Class<? extends S> buildChecked() throws ClassNotFoundException {\n      if (!nullOk && foundClass == null) {\n        throw new ClassNotFoundException(\n            \"Cannot find class; alternatives: \" + Joiner.on(\", \").join(classNames));\n      }\n      return (Class<? extends S>) foundClass;\n    }\n\n    /**\n     * Returns the first implementation or throws RuntimeException if one was not found.\n     *\n     * @param <S> Java superclass\n     * @return a {@link Class} for the first implementation found\n     * @throws RuntimeException if no implementation was found\n     */\n    @SuppressWarnings(\"unchecked\")\n    public <S> Class<? extends S> build() {\n      if (!nullOk && foundClass == null) {\n        throw new RuntimeException(\n            \"Cannot find class; alternatives: \" + Joiner.on(\", \").join(classNames));\n      }","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/common/src/main/java/org/apache/iceberg/common/DynClasses.java#L86-L122","documentation":"DynClasses.Builder.buildChecked() throws ClassNotFoundException when none of the candidate class names could be loaded and nullOk is false. It is the checked variant: callers are forced to handle the missing-class case. The message lists every alternative name that was tried.","triggerScenarios":"Calling DynClasses.builder().impl(\"a.B\").impl(\"c.D\").buildChecked() where every impl name fails to load (class absent, wrong name, or classloader can't see it).","commonSituations":"Detecting engine/runtime versions by trying class names (e.g. Spark 2 vs 3 classes) on a runtime that has neither; typos in fully-qualified names; shaded/missing jars on the classpath.","solutions":["Check the listed alternatives against the actual classpath; add the jar that provides one of them (e.g. the correct Spark/Hive version).","Verify the fully-qualified class names — package renames across versions are the usual culprit.","Call nullOk(true) if absence is acceptable, and handle the null Class explicitly.","Use build() (RuntimeException) or a default impl(...) that always matches to avoid a hard failure."],"exampleFix":"// before\nClass<?> cls = DynClasses.builder().impl(\"org.apache.spark.sql.catalyst.OldClass\").buildChecked();\n// after\nClass<?> cls = DynClasses.builder()\n    .impl(\"org.apache.spark.sql.catalyst.NewClass\")\n    .impl(\"org.apache.spark.sql.catalyst.OldClass\")\n    .buildChecked();","handlingStrategy":"try-catch","validationCode":"for (String name : new String[]{\"com.example.ImplA\", \"com.example.ImplB\"}) {\n  try {\n    Class.forName(name);\n    return; // at least one candidate exists\n  } catch (ClassNotFoundException ignored) { }\n}\nthrow new IllegalStateException(\"None of the candidate classes are on the classpath; add the required dependency\");","typeGuard":null,"tryCatchPattern":"try {\n  Class<?> cls = DynClasses.builder().impl(\"com.example.ImplA\").impl(\"com.example.ImplB\").buildChecked();\n} catch (ClassNotFoundException e) {\n  // no candidate found: log the alternatives and fall back or fail fast\n}","preventionTips":["List candidates for every known version of the target library","Fail fast at startup rather than lazily in a job","Check the classpath (mvn dependency:tree / spark.jars) for the jar providing the class","Use nullOk(true) only when absence genuinely has a supported fallback"],"tags":["reflection","classpath","dependency"],"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"}