{"record":{"id":"c8527434db371698","repo":"apache/beam","slug":"failed-to-load-user-provided-jar-s","errorCode":null,"errorMessage":"Failed to load user-provided jar(s).","messagePattern":"Failed to load user-provided jar\\(s\\)\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/rel/BeamCalcRel.java","lineNumber":308,"sourceCode":"      this.outputSchema = outputSchema;\n      this.verifyRowValues = verifyRowValues;\n      this.jarPaths = jarPaths;\n      this.fieldAccess = fieldAccess;\n      this.collectErrors = collectErrors;\n\n      // validate generated code\n      compile(processElementBlock, jarPaths);\n    }\n\n    private static ScriptEvaluator compile(String processElementBlock, List<String> jarPaths) {\n      ScriptEvaluator se = new ScriptEvaluator();\n      if (!jarPaths.isEmpty()) {\n        try {\n          JavaUdfLoader udfLoader = new JavaUdfLoader();\n          ClassLoader classLoader = udfLoader.createClassLoader(jarPaths);\n          se.setParentClassLoader(classLoader);\n        } catch (IOException e) {\n          throw new RuntimeException(\"Failed to load user-provided jar(s).\", e);\n        }\n      }\n      se.setParameters(\n          new String[] {rowParam.name, DataContext.ROOT.name},\n          new Class[] {(Class) rowParam.getType(), (Class) DataContext.ROOT.getType()});\n      se.setReturnType(Object[].class);\n      try {\n        se.cook(processElementBlock);\n      } catch (CompileException e) {\n        throw new UnsupportedOperationException(\n            \"Could not compile CalcFn: \" + processElementBlock, e);\n      }\n      return se;\n    }\n\n    @Setup\n    public void setup() {\n      this.se = compile(processElementBlock, jarPaths);","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/rel/BeamCalcRel.java#L290-L326","documentation":"Beam SQL loads user-provided UDF jars into a custom class loader before compiling the generated CalcFn Java code. If reading any of the jar paths throws IOException, the setup fails with this RuntimeException wrapping the cause. It means the SQL pipeline cannot access the jar files given in the UDF clause (e.g. via UDFProvider or 'jar_path' options).","triggerScenarios":"Calling JavaUdfLoader.createClassLoader(jarPaths) during CalcFn.setup or compile with a jar path that is missing, unreadable, a bad URL, or a corrupt/nonexistent artifact (e.g. wrong gs:// or http path in USING/jar options).","commonSituations":"Typos in the jar path in CREATE FUNCTION ... USING JAR 'path'; remote jar not accessible (missing credentials, wrong bucket, network failure); jar deleted between pipeline submission and worker startup; malformed maven coordinate.","solutions":["Verify each jar path is correct and reachable from the worker (file exists locally or bucket/URL is accessible)","Check the wrapped IOException cause for the actual failing path or connection problem","If using remote storage, confirm worker credentials/permissions (e.g. GCS/ADLS access for the Dataflow worker)","Pre-download or stage jars with the pipeline (--filesToStage or dependency staging) instead of fetching at runtime"],"exampleFix":"// before\nCREATE FUNCTION MYFN AS 'com.x.MyFn' USING JAR 'gs://wrong-bucket/udf.jar';\n// after\nCREATE FUNCTION MYFN AS 'com.x.MyFn' USING JAR 'gs://my-correct-bucket/udf.jar';","handlingStrategy":"validation","validationCode":"for (String path : jarPaths) {\n  if (!(new java.io.File(path).exists()) && !path.startsWith(\"gs://\") && !path.startsWith(\"http\")) {\n    throw new IllegalArgumentException(\"Jar not found: \" + path);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  ClassLoader cl = udfLoader.createClassLoader(jarPaths);\n} catch (IOException e) {\n  throw new IllegalStateException(\"Check jar paths/credentials: \" + e.getMessage(), e);\n}","preventionTips":["Validate jar paths at pipeline construction time","Stage UDF jars with the pipeline instead of remote fetch at Setup time","Verify worker service-account permissions for remote jar storage","Log the resolved jar paths before loading"],"tags":["java","apache-beam","sql","udf","classpath"],"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-14T16:17:12.679Z"}