{"record":{"id":"1ce531e17d31e6b8","repo":"apache/flink","slug":"python-command-line-option-detected-but-the-flink","errorCode":null,"errorMessage":"Python command line option detected but the flink-python module seems to be missing or not working as expected.","messagePattern":"Python command line option detected but the flink-python module seems to be missing or not working as expected\\.","errorType":"exception","errorClass":"CliArgsException","httpStatus":null,"severity":"error","filePath":"flink-clients/src/main/java/org/apache/flink/client/cli/ProgramOptionsUtils.java","lineNumber":92,"sourceCode":"                || line.hasOption(PYTHON_PATH.getOpt());\n    }\n\n    public static ProgramOptions createPythonProgramOptions(CommandLine line)\n            throws CliArgsException {\n        try {\n            ClassLoader classLoader = getPythonClassLoader();\n            Class<?> pythonProgramOptionsClazz =\n                    Class.forName(\n                            \"org.apache.flink.client.cli.PythonProgramOptions\", false, classLoader);\n            Constructor<?> constructor =\n                    pythonProgramOptionsClazz.getConstructor(CommandLine.class);\n            return (ProgramOptions) constructor.newInstance(line);\n        } catch (InstantiationException\n                | InvocationTargetException\n                | NoSuchMethodException\n                | IllegalAccessException\n                | ClassNotFoundException e) {\n            throw new CliArgsException(\n                    \"Python command line option detected but the flink-python module seems to be missing \"\n                            + \"or not working as expected.\",\n                    e);\n        }\n    }\n\n    private static ClassLoader getPythonClassLoader() {\n        try {\n            return new URLClassLoader(\n                    new URL[] {PackagedProgramUtils.getPythonJar()},\n                    Thread.currentThread().getContextClassLoader());\n        } catch (RuntimeException e) {\n            LOG.warn(\n                    \"An attempt to load the flink-python jar from the \\\"opt\\\" directory failed, \"\n                            + \"fall back to use the context class loader.\",\n                    e);\n            return Thread.currentThread().getContextClassLoader();\n        }","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-clients/src/main/java/org/apache/flink/client/cli/ProgramOptionsUtils.java#L74-L110","documentation":"Thrown by ProgramOptionsUtils.createPythonProgramOptions when a Python CLI option (-py, -pyfl, -pym, -pyreq, -pyarch, -pyexec, -pyclientexec, -pp) is detected but the flink-python module (PythonProgramOptions class) cannot be loaded. The method attempts to load the Python jar via a URLClassLoader constructed from PackagedProgramUtils.getPythonJar(), and if Class.forName or constructor invocation fails, it wraps the cause in CliArgsException. This means the Python integration layer is not available.","triggerScenarios":"Using -py or -pyfl options when the flink-python JAR is not present in FLINK_HOME/opt/ or on the classpath; the JAR exists but is corrupted or version-incompatible; PackagedProgramUtils.getPythonJar() cannot locate the Python jar in the expected directory.","commonSituations":"Minimal Flink installation without the Python component; version mismatch between the flink-python JAR and the core Flink distribution; custom container images that didn't include the opt/flink-python*.jar.","solutions":["Install the flink-python JAR: copy or symlink flink-dist's opt/flink-python-<version>.jar into the lib/ directory or ensure it's in FLINK_HOME/opt/","Verify PyFlink version matches the Flink distribution version exactly","Use pip install apache-flink==<matching-version> to get a compatible Python package"],"exampleFix":"# before (Python jar missing)\nflink run -py my_job.py\n\n# after\n# ensure the jar is in place\ncp $FLINK_HOME/opt/flink-python-*.jar $FLINK_HOME/lib/\nflink run -py my_job.py","handlingStrategy":"validation","validationCode":"// Check Python jar availability before using Python options:\ntry {\n    URL pythonJar = PackagedProgramUtils.getPythonJar();\n    if (pythonJar == null || !new File(pythonJar.toURI()).exists()) {\n        System.err.println(\"flink-python JAR not found. Install it in opt/ or lib/.\");\n    }\n} catch (Exception e) {\n    System.err.println(\"Cannot locate flink-python JAR: \" + e.getMessage());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ensure flink-python-<version>.jar is in FLINK_HOME/opt/ or lib/","Match the PyFlink version exactly with the Flink distribution version","Install apache-flink via pip with the matching version"],"tags":["cli","python","classpath","module-missing"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}