{"record":{"id":"9a6a5915acb7ca09","repo":"apache/beam","slug":"failed-to-load-user-defined-scalar-function-functionfullname","errorCode":null,"errorMessage":"Failed to load user-defined scalar function ${functionFullName} from ${jarPath}","messagePattern":"Failed to load user-defined scalar function (.+?) from (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/JavaUdfLoader.java","lineNumber":88,"sourceCode":"  public ScalarFn loadScalarFunction(List<String> functionPath, String jarPath) {\n    String functionFullName = String.join(\".\", functionPath);\n    try {\n      FunctionDefinitions functionDefinitions = loadJar(jarPath);\n      if (!functionDefinitions.scalarFunctions().containsKey(functionPath)) {\n        throw new IllegalArgumentException(\n            String.format(\n                \"No implementation of scalar function %s found in %s.%n\"\n                    + \" 1. Create a class implementing %s and annotate it with @AutoService(%s.class).%n\"\n                    + \" 2. Add function %s to the class's userDefinedScalarFunctions implementation.\",\n                functionFullName,\n                jarPath,\n                UdfProvider.class.getSimpleName(),\n                UdfProvider.class.getSimpleName(),\n                functionFullName));\n      }\n      return functionDefinitions.scalarFunctions().get(functionPath);\n    } catch (IOException e) {\n      throw new RuntimeException(\n          String.format(\n              \"Failed to load user-defined scalar function %s from %s\", functionFullName, jarPath),\n          e);\n    }\n  }\n\n  /** Load a user-defined aggregate function from the specified jar. */\n  public AggregateFn loadAggregateFunction(List<String> functionPath, String jarPath) {\n    String functionFullName = String.join(\".\", functionPath);\n    try {\n      FunctionDefinitions functionDefinitions = loadJar(jarPath);\n      if (!functionDefinitions.aggregateFunctions().containsKey(functionPath)) {\n        throw new IllegalArgumentException(\n            String.format(\n                \"No implementation of aggregate function %s found in %s.%n\"\n                    + \" 1. Create a class implementing %s and annotate it with @AutoService(%s.class).%n\"\n                    + \" 2. Add function %s to the class's userDefinedAggregateFunctions implementation.\",\n                functionFullName,","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/JavaUdfLoader.java#L70-L106","documentation":"JavaUdfLoader.loadScalarFunction() wraps any IOException from loadJar(jarPath) (jar open/read/classloading) into RuntimeException 'Failed to load user-defined scalar function %s from %s'. The jar could not be read at all — not that the function is missing — so the function lookup never happened.","triggerScenarios":"loadScalarFunction called with a jarPath that does not exist, is unreadable, is not a valid jar, or whose classes fail to load (URLClassLoader / loadJar throws IOException).","commonSituations":"Wrong file path or missing file on the runner's filesystem (the path is local to the worker); permission problems; corrupted or non-jar file; classloader conflicts inside a fat jar.","solutions":["Verify jarPath points to an existing, readable jar on the node executing the query.","Open the jar manually (jar tf <path>) to confirm validity and the UdfProvider service file.","Check file permissions and that the jar was staged/uploaded to the runner environment.","Inspect the cause IOException for the underlying read/load error."],"exampleFix":"// before\nnew JavaUdfLoader().loadScalarFunction(ImmutableList.of(\"myfn\"), \"/wrong/path/udf.jar\");\n// after\nnew JavaUdfLoader().loadScalarFunction(ImmutableList.of(\"myfn\"), \"/correct/path/udf.jar\");","handlingStrategy":"try-catch","validationCode":"File jar = new File(jarPath);\nif (!jar.isFile() || !jar.canRead()) {\n  throw new IllegalArgumentException(\"UDF jar missing or unreadable: \" + jarPath);\n}","typeGuard":null,"tryCatchPattern":"try {\n  ScalarFn fn = udfLoader.loadScalarFunction(fnPath, jarPath);\n} catch (RuntimeException e) {\n  if (e.getMessage().startsWith(\"Failed to load user-defined scalar function\")) {\n    LOG.error(\"Could not read jar {}: {}\", jarPath, e.getCause().getMessage());\n  }\n  throw e;\n}","preventionTips":["Ensure jars are staged to every worker node's filesystem","Validate jar integrity (jar tf) after upload","Check read permissions in containerized runners","Resolve jar paths from a single configuration source to avoid typos"],"tags":["udf","io","classpath","beam"],"backgroundTag":"file-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-15T02:17:10.978Z"}