{"record":{"id":"02bd60d41f29269a","repo":"apache/beam","slug":"failed-to-load-user-defined-aggregate-function","errorCode":null,"errorMessage":"Failed to load user-defined aggregate function ${functionFullName} from ${jarPath}","messagePattern":"Failed to load user-defined aggregate 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":114,"sourceCode":"  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,\n                jarPath,\n                UdfProvider.class.getSimpleName(),\n                UdfProvider.class.getSimpleName(),\n                functionFullName));\n      }\n      return functionDefinitions.aggregateFunctions().get(functionPath);\n    } catch (IOException e) {\n      throw new RuntimeException(\n          String.format(\n              \"Failed to load user-defined aggregate function %s from %s\",\n              functionFullName, jarPath),\n          e);\n    }\n  }\n\n  /**\n   * Creates a temporary local copy of the file at {@code inputPath}, and returns a handle to the\n   * local copy.\n   */\n  private File downloadFile(String inputPath, String mimeType) throws IOException {\n    Preconditions.checkArgument(!inputPath.isEmpty(), \"Path cannot be empty.\");\n\n    // Issue warning when downloading from public repositories\n    if (inputPath.startsWith(\"http://\") || inputPath.startsWith(\"https://\")) {\n      if (inputPath.contains(\"repo.maven.apache.org\")\n          || inputPath.contains(\"repo1.maven.org\")","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/JavaUdfLoader.java#L96-L132","documentation":"JavaUdfLoader.loadAggregateFunction() converts IOException thrown by loadJar(jarPath) into RuntimeException 'Failed to load user-defined aggregate function %s from %s'. The aggregate function lookup never occurs because the jar itself could not be opened, read, or its classes loaded.","triggerScenarios":"loadAggregateFunction invoked with a jarPath that is missing, unreadable, corrupt/not a jar, or whose provider classes fail to load (IOException in loadJar).","commonSituations":"Jar not present on the worker node; path typo; permission problems; corrupted upload; classloader conflicts inside the jar.","solutions":["Confirm the jar exists and is readable at jarPath from the process executing the query.","Validate the jar with jar tf and confirm the UdfProvider service registration is inside.","Fix staging/upload of the jar to the runner environment.","Read the wrapped IOException cause for the precise failure."],"exampleFix":"// before\nloader.loadAggregateFunction(ImmutableList.of(\"myagg\"), \"missing.jar\");\n// after (validate first)\nif (!new File(jarPath).exists()) throw new IllegalArgumentException(\"missing jar\");\nloader.loadAggregateFunction(ImmutableList.of(\"myagg\"), jarPath);","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  AggregateFn fn = udfLoader.loadAggregateFunction(fnPath, jarPath);\n} catch (RuntimeException e) {\n  if (e.getMessage().startsWith(\"Failed to load user-defined aggregate function\")) {\n    LOG.error(\"Could not read jar {}: {}\", jarPath, e.getCause().getMessage());\n  }\n  throw e;\n}","preventionTips":["Verify jar presence/readability on workers before query execution","Detect corrupted jars during deployment with a load check","Avoid duplicate/conflicting classpaths that break classloading","Log and monitor the IOException cause for infrastructure issues"],"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"}