apache/beam · critical · RuntimeException

Failed to instantiate handler

Error message

Failed to instantiate handler: {handlerClass.getName()}

What it means

RemoteInference's DoFn.setup() reflectively instantiates the configured RemoteInference handler class. Any exception during construction (bad constructor args, missing deps, handler's own init failure) is wrapped in a RuntimeException "Failed to instantiate handler: <class>" with the original cause retained.

Solutions

Read e.getCause() for the root constructor failure.
Verify the handler class name/factory config points to an existing class with the expected constructor.
Ensure all handler dependencies are bundled in the staged jar/container available on workers.
Provide any credentials/env vars the handler needs at worker startup.

Example fix

// before
--remoteInferenceHandlerClass=com.example.Handler (class not in fat jar)
// after
mvn shade: include com.example.Handler + deps in the job jar staged to workers

Defensive patterns

Strategy: validation

Validate before calling

Class.forName(handlerClassName).getDeclaredConstructor().setAccessible(true); // fail fast in main() before submitting the job

Try / catch

try { launcher.run(); } catch (RuntimeException e) { if (e.getMessage().startsWith("Failed to instantiate handler")) { LOG.error("handler init failed", e.getCause()); } throw e; }

Prevention

Shade all handler dependencies into the job jar
Validate the handler class name and constructor signature at job submission
Pre-create handler instances in a local dry-run test
Ensure worker containers carry required config/credentials

When it happens

Trigger: A pipeline using RemoteInference where handlerClass has no suitable constructor, its constructor throws (bad endpoint, missing config), or required classes/jars are absent on the worker at setup time.

Common situations: Fat jar missing handler dependencies on workers, typo'd handler class name in pipeline options, handler requiring env vars/credentials not staged to the worker, and classpath version conflicts.

Related errors

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

Appendix: source

Thrown at sdks/java/ml/inference/remote/src/main/java/org/apache/beam/sdk/ml/inference/remote/RemoteInference.java:264

      }

      /** Instantiate the model handler and client. */
      @Setup
      public void setupHandler() {
        try {
          this.modelHandler = handlerClass.getDeclaredConstructor().newInstance();
          this.modelHandler.createClient(parameters);
          if (throttleDelaySecs > 0) {
            this.throttler =
                new ReactiveThrottler(
                    samplePeriodMs,
                    sampleUpdateMs,
                    overloadRatio,
                    "RemoteInference",
                    throttleDelaySecs);
          }
        } catch (Exception e) {
          throw new RuntimeException("Failed to instantiate handler: " + handlerClass.getName(), e);
        }
      }

      /** Perform Inference. */
      @ProcessElement
      public void processElement(ProcessContext c) throws Exception {
        Iterable<PredictionResult<InputT, OutputT>> response =
            retryHandler.execute(
                () -> {
                  if (throttler != null) {
                    throttler.throttle();
                  }
                  long reqTime = System.currentTimeMillis();
                  if (modelHandler == null) {
                    throw new IllegalStateException("modelHandler is not initialized");
                  }
                  Iterable<PredictionResult<InputT, OutputT>> result =
                      modelHandler.request(c.element());

View on GitHub (pinned to 12126d8942)