{"record":{"id":"01238b8de525e57f","repo":"apache/beam","slug":"expected-to-find-a-single-mapping-constructor-method-but","errorCode":null,"errorMessage":"Expected to find a single mapping constructor method but found ${mappingConstructorMethods.size()} Payload was ${payload}","messagePattern":"Expected to find a single mapping constructor method but found (.+?) Payload was (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/JavaClassLookupTransformProvider.java","lineNumber":469,"sourceCode":"  private Method findMappingConstructorMethod(\n      Method[] methods, JavaClassLookupPayload payload, AllowedClass allowListClass) {\n\n    Row constructorRow = decodeRow(payload.getConstructorSchema(), payload.getConstructorPayload());\n\n    List<Method> mappingConstructorMethods =\n        Arrays.stream(methods)\n            .filter(\n                m -> isConstructorMethodForName(m, payload.getConstructorMethod(), allowListClass))\n            .filter(m -> m.getParameterCount() == payload.getConstructorSchema().getFieldsCount())\n            .filter(m -> parametersCompatible(m.getParameters(), constructorRow))\n            .collect(Collectors.toList());\n\n    if (mappingConstructorMethods.size() == 0) {\n      throw new RuntimeException(\n          \"Could not find a matching constructor method. When using field names, make sure they \"\n              + \"are available in the compiled Java class.\");\n    } else if (mappingConstructorMethods.size() != 1) {\n      throw new RuntimeException(\n          \"Expected to find a single mapping constructor method but found \"\n              + mappingConstructorMethods.size()\n              + \" Payload was \"\n              + payload);\n    }\n    return mappingConstructorMethods.get(0);\n  }\n\n  @AutoValue\n  public abstract static class AllowList {\n\n    public static AllowList nothing() {\n      return create(ALLOW_LIST_VERSION, Collections.emptyList());\n    }\n\n    public static AllowList everything() {\n      return create(\n          ALLOW_LIST_VERSION,","sourceCodeStart":451,"sourceCodeEnd":487,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/JavaClassLookupTransformProvider.java#L451-L487","documentation":"findMappingConstructorMethod matched multiple methods satisfying the allowlist, arity, and compatibility filters. The provider requires exactly one and throws RuntimeException including the count and the full payload for debugging.","triggerScenarios":"Overloaded methods with the same name and arity (both allowed and compatible with the Row), e.g. (int, String) vs (long, String) overloads, or the same name matched via both the annotation branch and the name branch.","commonSituations":"Adding overloads for convenience to existing constructor methods; autoboxing widening making several overloads compatible; duplicate @MultiLanguageConstructorMethod names on multiple methods.","solutions":["Keep exactly one overload with the given name and arity; delete or rename extra overloads.","Use distinct @MultiLanguageConstructorMethod names for each variant.","Tighten parameter types so only one method is parametersCompatible with the Row.","Catch RuntimeException and use the embedded payload to identify which name/arity is ambiguous."],"exampleFix":"// before\nstatic T create(int a, String b) {...}\nstatic T create(long a, String b) {...}\n// after\nstatic T create(long a, String b) {...}","handlingStrategy":"try-catch","validationCode":"long matches = Arrays.stream(Target.class.getMethods()).filter(m -> m.getName().equals(name)).filter(m -> m.getParameterCount() == schema.getFieldsCount()).count(); if (matches != 1) throw new IllegalStateException(\"Expected 1 matching method, found \" + matches);","typeGuard":null,"tryCatchPattern":"try { method(payload); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"Expected to find a single mapping constructor method\")) { /* dedupe overloads or rename */ } throw e; }","preventionTips":["One overload per constructor-method name and arity","Give each variant a distinct @MultiLanguageConstructorMethod name","Avoid widening-compatible overload pairs","Count matching methods in a startup self-check"],"tags":["java","reflection","ambiguity","method-overload"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}