apache/seatunnel · error · IllegalStateException

python.executable must be an absolute path or a bare command

Error message

python.executable must be an absolute path or a bare command name: {}

What it means

Thrown when python.executable is configured as a relative path containing a directory component (e.g. 'venv/bin/python' or './python'), which the policy rejects: it must be either an absolute path or a bare command name. Relative paths are ambiguous across worker working directories.

Source

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

                            + " does not contain a usable absolute path");
        }
        return new ArrayList<>(allowedExecutables);
    }

    private static Path resolveConfiguredExecutable(String configuredExecutable)
            throws IOException {
        Path configuredPath = Paths.get(configuredExecutable);
        Path resolvedPath;
        if (configuredPath.isAbsolute()) {
            resolvedPath = normalize(configuredPath);
        } else if (configuredPath.getParent() == null) {
            resolvedPath = resolveCommandFromPath(configuredExecutable);
            if (resolvedPath == null) {
                throw new IOException(
                        "Unable to resolve python.executable from PATH: " + configuredExecutable);
            }
        } else {
            throw new IllegalStateException(
                    "python.executable must be an absolute path or a bare command name: "
                            + configuredExecutable);
        }
        if (!Files.isRegularFile(resolvedPath) || !Files.isExecutable(resolvedPath)) {
            throw new IOException(
                    "python.executable does not resolve to an executable file: " + resolvedPath);
        }
        return resolvedPath;
    }

    private static Path resolveCommandFromPath(String command) {
        String pathValue = System.getenv("PATH");
        if (pathValue == null || pathValue.trim().isEmpty()) {
            return null;
        }
        for (String directory : pathValue.split(Pattern.quote(File.pathSeparator))) {
            if (directory == null || directory.trim().isEmpty()) {
                continue;

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Convert the path to absolute: venv/bin/python -> /opt/app/venv/bin/python
  2. Or drop the directory part and rely on PATH lookup with a bare name like 'python'
  3. Verify the same absolute path exists on every worker node

Example fix

// before
pythonExecutable = "venv/bin/python"
// after
pythonExecutable = "/opt/app/venv/bin/python"
Defensive patterns

Strategy: validation

Validate before calling

Path p = Paths.get(config.getPythonExecutable());
if (p.getParent() != null && !p.isAbsolute())
    throw new IllegalArgumentException("python.executable must be absolute or a bare command name");

Prevention

When it happens

Trigger: Configuring python.executable = 'venv/bin/python' or './bin/python' — a path with a parent that is not absolute — causing resolveConfiguredExecutable to hit the else branch and throw IllegalStateException.

Common situations: Copying a relative venv path from a README; assuming the worker's working directory is the project root; portable config files shared between nodes with different layouts.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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