apache/beam · error · IllegalArgumentException

Failed to load class override

Error message

Failed to load class override 

What it means

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.

Solutions

1. Correct the fully-qualified class name in the config to a class present on the worker classpath.
2. Bundle the override class in the submitted jar / fat jar so it exists at runtime.
3. Verify the class implements BiFunction<BigtableDataSettings.Builder, PipelineOptions, BigtableDataSettings.Builder> and has a no-arg constructor.

Example fix

// before
config.setSettingsOverride("com.example.OldOverride"); // renamed away
// after
config.setSettingsOverride("com.example.BigtableSettingsOverride");

Class<?> c;
try { c = Class.forName(overrideClassName); } catch (ClassNotFoundException e) { throw new IllegalArgumentException("Override class not on classpath: " + overrideClassName); }
if (!BiFunction.class.isAssignableFrom(c)) throw new IllegalArgumentException("Override must be a BiFunction");

boolean isLoadable(String name) { try { Class.forName(name); return true; } catch (ClassNotFoundException e) { return false; } }

try { settings = translator.buildBigtableDataSettings(config, options); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Failed to load class override")) { /* fix config/jar */ } throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot find requested QueryPlanner class
• Could not find class
• Could not find class:
• Could not find class
• Could not instantiate class

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/a5a7b9c3a159856b. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigtable/BigtableConfigTranslator.java:187

      PipelineOptions pipelineOptions) {
    if (override == null) {
      return dataBuilder;
    }

    BiFunction<BigtableDataSettings.Builder, PipelineOptions, BigtableDataSettings.Builder>
        overrideFunction;
    try {
      overrideFunction =
          InstanceBuilder.ofType(
                  new TypeDescriptor<
                      BiFunction<
                          BigtableDataSettings.Builder,
                          PipelineOptions,
                          BigtableDataSettings.Builder>>() {})
              .fromClassName(override)
              .build();
    } catch (ClassNotFoundException e) {
      throw new IllegalArgumentException("Failed to load class override " + override, e);
    }
    try {
      return overrideFunction.apply(dataBuilder, pipelineOptions);
    } catch (Exception e) {
      throw new IllegalStateException("Failed to apply override function for class " + override, e);
    }
  }

  private static void configureHeaderProvider(
      StubSettings.Builder<?, ?> stubSettings, PipelineOptions pipelineOptions) {

    ImmutableMap.Builder<String, String> headersBuilder =
        ImmutableMap.<String, String>builder()
            .put(
                GrpcUtil.USER_AGENT_KEY.name(),
                Objects.requireNonNull(pipelineOptions.getUserAgent()));

    stubSettings.setHeaderProvider(FixedHeaderProvider.create(headersBuilder.build()));

View on GitHub (pinned to 12126d8942)