apache/seatunnel · error · IllegalArgumentException

python.executable must not be blank

Error message

python.executable must not be blank

What it means

PythonSourceConfig.validate() throws this IllegalArgumentException when the configured python.executable option is null, empty, or whitespace-only. The Python source requires an interpreter path to spawn its subprocess, so a blank value makes the config invalid before any execution.

Source

Thrown at seatunnel-connectors-v2/connector-python/src/main/java/org/apache/seatunnel/connectors/seatunnel/python/source/PythonSourceConfig.java:86

    public String getPythonWorkingDirectory() {
        return pythonWorkingDirectory;
    }

    public String getFileFormatType() {
        return fileFormatType;
    }

    public String getFieldDelimiter() {
        return fieldDelimiter;
    }

    /**
     * Phase 1 keeps the stdout contract intentionally narrow so the first implementation can stay
     * compatible with the existing text deserializer.
     */
    private void validate() {
        if (StringUtils.isBlank(pythonExecutable)) {
            throw new IllegalArgumentException("python.executable must not be blank");
        }
        if (StringUtils.isBlank(pythonScriptPath)) {
            throw new IllegalArgumentException("python.script.path must not be blank");
        }
        if (!SUPPORTED_FILE_FORMAT.equalsIgnoreCase(fileFormatType)) {
            throw new IllegalArgumentException(
                    "Unsupported file_format_type: "
                            + fileFormatType
                            + ". Phase 1 supports only text");
        }
        if (fieldDelimiter == null) {
            throw new IllegalArgumentException("field_delimiter must not be null");
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Set python.executable in the source config to an absolute interpreter path, e.g. "/usr/bin/python3".
  2. Ensure the value has no surrounding whitespace-only content or stray quotes.
  3. Verify the interpreter exists on every worker node where the source will run.
  4. Combine with -Dpython.allowed.executables so the configured path is permitted by the execution policy.

Example fix

// before
Python {
  python.executable = ""
}
// after
Python {
  python.executable = "/usr/bin/python3"
}
Defensive patterns

Strategy: validation

Validate before calling

// Java: validate the map before constructing PythonSourceConfig
String exe = configMap.get("python.executable");
if (exe == null || exe.trim().isEmpty()) {
    throw new IllegalArgumentException("python.executable is required and must not be blank");
}

Try / catch

try { cfg = new PythonSourceConfig(configMap); } catch (IllegalArgumentException e) { LOG.error("Invalid python source config: {}", e.getMessage()); }

Prevention

When it happens

Trigger: Building PythonSourceConfig from a job config where the python.executable option is omitted or set to ""/whitespace; validate() runs during config construction and fails immediately.

Common situations: Copy-pasting a config template without filling in python.executable; relying on an old config key that no longer applies; assuming the server's default python is used instead of an explicit path.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/a3a0f60feac07e9e. Report an issue: GitHub.