{"record":{"id":"c1e5794f6e33683f","repo":"apache/beam","slug":"unable-to-instantiate-externaltransformbuilder-from","errorCode":null,"errorMessage":"Unable to instantiate ExternalTransformBuilder from constructor.","messagePattern":"Unable to instantiate ExternalTransformBuilder from constructor\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/expansion/ExternalTransformRegistrar.java","lineNumber":68,"sourceCode":"    ImmutableMap.Builder builder = ImmutableMap.<String, ExternalTransformBuilder>builder();\n    Map<String, Class<? extends ExternalTransformBuilder<?, ?, ?>>> knownBuilders = knownBuilders();\n    for (Entry<String, Class<? extends ExternalTransformBuilder<?, ?, ?>>> knownBuilder :\n        knownBuilders.entrySet()) {\n      Preconditions.checkState(\n          ExternalTransformBuilder.class.isAssignableFrom(knownBuilder.getValue()),\n          \"Provided identifier %s is not an ExternalTransformBuilder.\",\n          knownBuilder.getValue().getName());\n      try {\n        Constructor<? extends ExternalTransformBuilder> constructor =\n            knownBuilder.getValue().getDeclaredConstructor();\n\n        constructor.setAccessible(true);\n        builder.put(knownBuilder.getKey(), constructor.newInstance());\n\n      } catch (RuntimeException e) {\n        throw e;\n      } catch (Exception e) {\n        throw new RuntimeException(\n            \"Unable to instantiate ExternalTransformBuilder from constructor.\", e);\n      }\n    }\n    return builder.build();\n  }\n}\n","sourceCodeStart":50,"sourceCodeEnd":75,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/expansion/ExternalTransformRegistrar.java#L50-L75","documentation":"Beam's expansion service discovers ExternalTransformBuilder implementations via ServiceLoader and instantiates each with a no-arg constructor. If instantiation fails for any reason other than a RuntimeException (e.g. IllegalAccessException, InvocationTargetException from a throwing constructor, missing class), it is wrapped in this RuntimeException.","triggerScenarios":"Registering an ExternalTransformBuilder whose class has no accessible no-arg constructor, whose constructor throws during initialization, or which depends on classes not present in the expansion service classpath.","commonSituations":"Cross-language transform expansion: a Java transform JAR not fully shipped to the expansion service, a builder requiring injected state via constructor, constructor performing eager validation that fails (missing config/env).","solutions":["Ensure the builder class has a public no-arg constructor and keep it side-effect free.","Check the expansion service classpath includes the builder class and all its dependencies.","Inspect the cause (e.getCause()) for the constructor's underlying failure and fix that initialization error."],"exampleFix":"// before\nclass MyBuilder implements ExternalTransformBuilder<...> {\n  MyBuilder(Config c) { ... } // no no-arg constructor\n}\n// after\nclass MyBuilder implements ExternalTransformBuilder<...> {\n  public MyBuilder() {} // required by ExternalTransformRegistrar\n}\n","handlingStrategy":"validation","validationCode":"Class<?> c = Class.forName(builderName);\nif (!java.lang.reflect.Modifier.isPublic(c.getModifiers()) || c.getConstructors().length == 0)\n  throw new IllegalStateException(\"needs public no-arg constructor: \" + builderName);","typeGuard":null,"tryCatchPattern":"try { registrar.knownBuilderInstances(); } catch (RuntimeException e) { log.error(\"builder init failed\", e.getCause()); throw e; }","preventionTips":["Always provide a public no-arg constructor on ExternalTransformBuilder classes","Keep constructors free of side effects and external lookups","Verify expansion service shadow JAR contains all builder classes"],"tags":["beam","expansion-service","reflection","cross-language"],"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-14T16:17:12.679Z"}