{"record":{"id":"c8c5cb0adba952c2","repo":"apache/flink","slug":"found-optjarpath-size-s-jar","errorCode":null,"errorMessage":"Found {optJarPath.size()} %s jar.","messagePattern":"Found (.+?) (.+?) jar\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"flink-clients/src/main/java/org/apache/flink/client/program/PackagedProgramUtils.java","lineNumber":274,"sourceCode":"                    new SimpleFileVisitor<Path>() {\n                        @Override\n                        public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)\n                                throws IOException {\n                            FileVisitResult result = super.visitFile(file, attrs);\n                            if (file.getFileName().toString().startsWith(jarName)) {\n                                optJarPath.add(file);\n                            }\n                            return result;\n                        }\n                    });\n        } catch (IOException e) {\n            throw new RuntimeException(\n                    \"Exception encountered during finding the flink-python jar. This should not happen.\",\n                    e);\n        }\n\n        if (optJarPath.size() != 1) {\n            throw new RuntimeException(\n                    String.format(\"Found \" + optJarPath.size() + \" %s jar.\", jarName));\n        }\n\n        try {\n            return optJarPath.get(0).toUri().toURL();\n        } catch (MalformedURLException e) {\n            throw new RuntimeException(\"URL is invalid. This should not happen.\", e);\n        }\n    }\n}\n","sourceCodeStart":256,"sourceCodeEnd":285,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-clients/src/main/java/org/apache/flink/client/program/PackagedProgramUtils.java#L256-L285","documentation":"Thrown when the number of jars matching the target name in the opt directory is not exactly one. If zero are found, the jar is missing from the installation; if more than one, there are duplicates. Note: the message format has a bug — it uses String.format with a hardcoded concatenation and an unused %s placeholder, producing a garbled message like 'Found 2 %s jar.'.","triggerScenarios":"getOptJar finds zero or more than one jar whose filename starts with the target name (e.g., 'flink-python'). Triggered during PyFlink initialization when locating the python connector jar.","commonSituations":"Multiple versions of flink-python jar left in opt/ after an upgrade, or the jar was removed/renamed. Also seen with custom distributions that bundle extra jars with overlapping prefixes.","solutions":["List jars in $FLINK_HOME/opt and ensure exactly one matches the target name prefix.","Remove duplicate jars (keep only the version matching your Flink distribution).","If zero found, download/reinstall the correct flink-python jar for your Flink version.","Avoid manually copying jars with similar names into opt/."],"exampleFix":"# before: two flink-python jars present\nls $FLINK_HOME/opt/flink-python*\n# flink-python_2.12-1.17.jar  flink-python_2.12-1.18.jar\n\n# after: keep only the matching version\nrm $FLINK_HOME/opt/flink-python_2.12-1.17.jar","handlingStrategy":"validation","validationCode":"String optDir = System.getenv(ConfigConstants.ENV_FLINK_OPT_DIR);\nFile[] matches = new File(optDir).listFiles((d, name) -> name.startsWith(jarName));\nif (matches == null || matches.length != 1) {\n    throw new IllegalStateException(\"Expected exactly one \" + jarName + \" jar in \" + optDir);\n}","typeGuard":null,"tryCatchPattern":"try {\n    // code that triggers getOptJar\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"jar\")) {\n        // list and deduplicate jars in opt/\n    }\n    throw e;\n}","preventionTips":["Keep only one version of each jar in opt/.","Clean up old jars after Flink upgrades.","Avoid copying jars with overlapping name prefixes into opt/."],"tags":["python","packaged-program-utils","filesystem","duplicate-jars","flink-home"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}