{"record":{"id":"9f7ea3d9ceb8441a","repo":"apache/flink","slug":"exception-encountered-during-finding-the-flink-pyt","errorCode":null,"errorMessage":"Exception encountered during finding the flink-python jar. This should not happen.","messagePattern":"Exception encountered during finding the flink-python jar\\. This should not happen\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"flink-clients/src/main/java/org/apache/flink/client/program/PackagedProgramUtils.java","lineNumber":268,"sourceCode":"    private static URL getOptJar(String jarName) {\n        String flinkOptPath = System.getenv(ConfigConstants.ENV_FLINK_OPT_DIR);\n        final List<Path> optJarPath = new ArrayList<>();\n        try {\n            Files.walkFileTree(\n                    FileSystems.getDefault().getPath(flinkOptPath),\n                    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":250,"sourceCodeEnd":285,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-clients/src/main/java/org/apache/flink/client/program/PackagedProgramUtils.java#L250-L285","documentation":"Thrown when an IOException occurs while walking the Flink 'opt' directory to locate a jar (typically the flink-python jar). The method getOptJar uses Files.walkFileTree on the FLINK_OPT_DIR environment variable path. If that directory walk fails (directory missing, unreadable, or IO error), this RuntimeException is thrown.","triggerScenarios":"The FLINK_OPT_DIR environment variable points to a path that does not exist, is not a directory, or has an I/O error during traversal. Triggered when PyFlink or the SQL client tries to locate the python jar at startup.","commonSituations":"FLINK_HOME or FLINK_OPT_DIR set incorrectly, partial Flink installation missing the opt/ directory, or filesystem permissions preventing directory listing.","solutions":["Verify FLINK_HOME points to a complete Flink installation.","Check that $FLINK_HOME/opt exists and is readable.","Ensure FLINK_OPT_DIR env var (if set) points to the correct opt directory.","Reinstall Flink from a complete distribution if opt/ is missing."],"exampleFix":"# before: FLINK_HOME points to incomplete install\nexport FLINK_HOME=/opt/flink-incomplete\n\n# after: point to full installation\nexport FLINK_HOME=/opt/flink\nls $FLINK_HOME/opt/  # should contain flink-python jars","handlingStrategy":"validation","validationCode":"String optDir = System.getenv(ConfigConstants.ENV_FLINK_OPT_DIR);\nif (optDir == null || !new File(optDir).isDirectory()) {\n    throw new IllegalStateException(\"FLINK_OPT_DIR is not set or invalid: \" + optDir);\n}","typeGuard":null,"tryCatchPattern":"try {\n    // code that triggers PyFlink / getOptJar\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"finding the flink-python jar\")) {\n        // check FLINK_HOME and opt/ directory\n    }\n    throw e;\n}","preventionTips":["Set FLINK_HOME to a complete Flink installation.","Verify $FLINK_HOME/opt is present and readable.","Do not set FLINK_OPT_DIR to a custom path unless it mirrors the standard opt/ layout."],"tags":["python","packaged-program-utils","filesystem","environment","flink-home"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}