{"record":{"id":"a5a7b9c3a159856b","repo":"apache/beam","slug":"failed-to-load-class-override","errorCode":null,"errorMessage":"Failed to load class override ","messagePattern":"Failed to load class override ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigtable/BigtableConfigTranslator.java","lineNumber":187,"sourceCode":"      PipelineOptions pipelineOptions) {\n    if (override == null) {\n      return dataBuilder;\n    }\n\n    BiFunction<BigtableDataSettings.Builder, PipelineOptions, BigtableDataSettings.Builder>\n        overrideFunction;\n    try {\n      overrideFunction =\n          InstanceBuilder.ofType(\n                  new TypeDescriptor<\n                      BiFunction<\n                          BigtableDataSettings.Builder,\n                          PipelineOptions,\n                          BigtableDataSettings.Builder>>() {})\n              .fromClassName(override)\n              .build();\n    } catch (ClassNotFoundException e) {\n      throw new IllegalArgumentException(\"Failed to load class override \" + override, e);\n    }\n    try {\n      return overrideFunction.apply(dataBuilder, pipelineOptions);\n    } catch (Exception e) {\n      throw new IllegalStateException(\"Failed to apply override function for class \" + override, e);\n    }\n  }\n\n  private static void configureHeaderProvider(\n      StubSettings.Builder<?, ?> stubSettings, PipelineOptions pipelineOptions) {\n\n    ImmutableMap.Builder<String, String> headersBuilder =\n        ImmutableMap.<String, String>builder()\n            .put(\n                GrpcUtil.USER_AGENT_KEY.name(),\n                Objects.requireNonNull(pipelineOptions.getUserAgent()));\n\n    stubSettings.setHeaderProvider(FixedHeaderProvider.create(headersBuilder.build()));","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigtable/BigtableConfigTranslator.java#L169-L205","documentation":"BigtableConfigTranslator supports a settings-override class name that is reflectively instantiated as a BiFunction<BigtableDataSettings.Builder, PipelineOptions, ...>. When Class.forName/instantiation reports ClassNotFoundException, the translator throws this IllegalArgumentException naming the class it failed to load.","triggerScenarios":"Setting the override class name (e.g. via BigtableOptions/config) to a class that doesn't exist on the worker classpath, is misspelled, or isn't a valid BiFunction subclass.","commonSituations":"Custom override class not bundled in the job jar; typo in fully-qualified class name; refactor renamed the class without updating config; dependency-shading breaking the class package.","solutions":["Correct the fully-qualified class name in the config to a class present on the worker classpath.","Bundle the override class in the submitted jar / fat jar so it exists at runtime.","Verify the class implements BiFunction<BigtableDataSettings.Builder, PipelineOptions, BigtableDataSettings.Builder> and has a no-arg constructor."],"exampleFix":"// before\nconfig.setSettingsOverride(\"com.example.OldOverride\"); // renamed away\n// after\nconfig.setSettingsOverride(\"com.example.BigtableSettingsOverride\");","handlingStrategy":"validation","validationCode":"Class<?> c;\ntry { c = Class.forName(overrideClassName); } catch (ClassNotFoundException e) { throw new IllegalArgumentException(\"Override class not on classpath: \" + overrideClassName); }\nif (!BiFunction.class.isAssignableFrom(c)) throw new IllegalArgumentException(\"Override must be a BiFunction\");","typeGuard":"boolean isLoadable(String name) { try { Class.forName(name); return true; } catch (ClassNotFoundException e) { return false; } }","tryCatchPattern":"try { settings = translator.buildBigtableDataSettings(config, options); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Failed to load class override\")) { /* fix config/jar */ } throw e; }","preventionTips":["Keep the override class in the job's fat jar.","Reference the class via its Class object or a constant to survive refactors.","Smoke-test config translation locally with a DirectRunner."],"tags":["bigtable","reflection","classpath"],"backgroundTag":"class-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}