{"record":{"id":"73544e51461f18a6","repo":"apache/beam","slug":"failed-to-instantiate-handler-handlerclass-getname","errorCode":null,"errorMessage":"Failed to instantiate handler: {handlerClass.getName()}","messagePattern":"Failed to instantiate handler: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"sdks/java/ml/inference/remote/src/main/java/org/apache/beam/sdk/ml/inference/remote/RemoteInference.java","lineNumber":264,"sourceCode":"      }\n\n      /** Instantiate the model handler and client. */\n      @Setup\n      public void setupHandler() {\n        try {\n          this.modelHandler = handlerClass.getDeclaredConstructor().newInstance();\n          this.modelHandler.createClient(parameters);\n          if (throttleDelaySecs > 0) {\n            this.throttler =\n                new ReactiveThrottler(\n                    samplePeriodMs,\n                    sampleUpdateMs,\n                    overloadRatio,\n                    \"RemoteInference\",\n                    throttleDelaySecs);\n          }\n        } catch (Exception e) {\n          throw new RuntimeException(\"Failed to instantiate handler: \" + handlerClass.getName(), e);\n        }\n      }\n\n      /** Perform Inference. */\n      @ProcessElement\n      public void processElement(ProcessContext c) throws Exception {\n        Iterable<PredictionResult<InputT, OutputT>> response =\n            retryHandler.execute(\n                () -> {\n                  if (throttler != null) {\n                    throttler.throttle();\n                  }\n                  long reqTime = System.currentTimeMillis();\n                  if (modelHandler == null) {\n                    throw new IllegalStateException(\"modelHandler is not initialized\");\n                  }\n                  Iterable<PredictionResult<InputT, OutputT>> result =\n                      modelHandler.request(c.element());","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/ml/inference/remote/src/main/java/org/apache/beam/sdk/ml/inference/remote/RemoteInference.java#L246-L282","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n--remoteInferenceHandlerClass=com.example.Handler (class not in fat jar)\n// after\nmvn shade: include com.example.Handler + deps in the job jar staged to workers","handlingStrategy":"validation","validationCode":"Class.forName(handlerClassName).getDeclaredConstructor().setAccessible(true); // fail fast in main() before submitting the job","typeGuard":null,"tryCatchPattern":"try { launcher.run(); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"Failed to instantiate handler\")) { LOG.error(\"handler init failed\", e.getCause()); } throw e; }","preventionTips":["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"],"tags":["java","beam","reflection","worker-setup"],"backgroundTag":"module-init-failed","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"}