{"record":{"id":"27b8c8d6218bbba9","repo":"apache/dolphinscheduler","slug":"run-python-task-error","errorCode":null,"errorMessage":"run python task error","messagePattern":"run python task error","errorType":"exception","errorClass":"TaskException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-task-plugin/dolphinscheduler-task-python/src/main/java/org/apache/dolphinscheduler/plugin/task/python/PythonTask.java","lineNumber":97,"sourceCode":"            // generate the file path of this python script\n            String pythonScriptFile = buildPythonCommandFilePath();\n\n            // create this file\n            createPythonCommandFileIfNotExists(pythonScriptContent, pythonScriptFile);\n\n            IShellInterceptorBuilder<?, ?> shellActuatorBuilder = ShellInterceptorBuilderFactory.newBuilder()\n                    .appendScript(buildPythonExecuteCommand(pythonScriptFile));\n\n            TaskResponse taskResponse = shellCommandExecutor.run(shellActuatorBuilder, taskCallBack);\n            setExitStatusCode(taskResponse.getExitStatusCode());\n            setProcessId(taskResponse.getProcessId());\n            setTaskOutputParams(shellCommandExecutor.getTaskOutputParams());\n            pythonParameters.dealOutParam(shellCommandExecutor.getTaskOutputParams());\n            taskRequest.setVarPool(pythonParameters.getVarPool());\n        } catch (Exception e) {\n            log.error(\"python task failure\", e);\n            setExitStatusCode(TaskConstants.EXIT_CODE_FAILURE);\n            throw new TaskException(\"run python task error\", e);\n        }\n    }\n\n    @Override\n    public void cancel() throws TaskException {\n        // cancel process\n        try {\n            shellCommandExecutor.cancelApplication();\n        } catch (Exception e) {\n            throw new TaskException(\"cancel application error\", e);\n        }\n    }\n\n    @Override\n    public AbstractParameters getParameters() {\n        return pythonParameters;\n    }\n","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-task-plugin/dolphinscheduler-task-python/src/main/java/org/apache/dolphinscheduler/plugin/task/python/PythonTask.java#L79-L115","documentation":"PythonTask.handle wraps any exception raised while executing the submitted Python script via ShellCommandExecutor into a generic TaskException with message \"run python task error\". The original exception is attached as the cause; the task's exit status is also set to failure before throwing. It signals that the Python task execution failed for any reason (command failure, parameter handling, IO).","triggerScenarios":"Calling PythonTask.handle() when: the python executable is missing or fails (non-zero exit), the shell command executor throws an IOException/InterruptedException, or dealOutParam/setVarPool throws while processing task output parameters.","commonSituations":"python not installed or not on PATH on the worker; script syntax/runtime errors; bad varPool/output-parameter references in the task definition; worker interrupted during execution.","solutions":["Inspect the logged 'python task failure' stack trace and the task instance log for the real root cause (python exit code, missing binary, script error).","Verify python is installed and on PATH on the worker host, and that PYTHON_HOME/env is configured if required.","Run the Python script manually on the worker with the same user to reproduce syntax/import/runtime errors.","Check taskParams rawScript and output parameter (varPool) definitions for invalid references or malformed JSON."],"exampleFix":"// before: opaque failure\nthrow new TaskException(\"run python task error\", e);\n// after: surface root cause in message\nthrow new TaskException(\"run python task error: \" + e.getMessage(), e);","handlingStrategy":"try-catch","validationCode":"// before submitting\nProcessBuilder check = new ProcessBuilder(\"python\", \"--version\");\ncheck.start().waitFor(); // throws IOException if python is missing\nassert rawScript != null && !rawScript.isBlank();","typeGuard":"boolean hasScript(PythonParameters p) { return p != null && p.getRawScript() != null && !p.getRawScript().isBlank(); }","tryCatchPattern":"try {\n    pythonTask.handle();\n} catch (TaskException e) {\n    logger.error(\"Python task failed: {}\", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e);\n    // inspect worker logs / python exit code before retrying\n}","preventionTips":["Pre-install the exact python version on all worker hosts and verify with a startup health check.","Test the script manually on the worker with the same OS user before scheduling it.","Keep varPool/output param definitions consistent with what the script writes."],"tags":["task-execution","python","shell-executor","worker"],"backgroundTag":"command-not-found","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}