apache/seatunnel · critical · IllegalStateException

Server property {} must contain at least one absolute execut

Error message

Server property {} must contain at least one absolute executable path

What it means

Thrown when the SeaTunnel Python source is used but the JVM system property 'python.allowed.executables' (PYTHON_ALLOWED_EXECUTABLES_PROPERTY) is unset or blank. This security allowlist of absolute Python interpreter paths is mandatory so workers never execute an arbitrary interpreter. The property must contain at least one absolute path before the source can run.

Source

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

    }

    private static void ensureEnabled() {
        if (Boolean.parseBoolean(
                System.getProperty(PYTHON_SOURCE_ENABLED_PROPERTY, Boolean.FALSE.toString()))) {
            return;
        }
        throw new IllegalStateException(
                "Python source is disabled by the server-side security policy. Set -D"
                        + PYTHON_SOURCE_ENABLED_PROPERTY
                        + "=true and configure -D"
                        + PYTHON_ALLOWED_EXECUTABLES_PROPERTY
                        + " with absolute interpreter paths on every worker node.");
    }

    private static List<Path> parseAllowedExecutables() {
        String rawAllowlist = System.getProperty(PYTHON_ALLOWED_EXECUTABLES_PROPERTY, "");
        if (rawAllowlist.trim().isEmpty()) {
            throw new IllegalStateException(
                    "Server property "
                            + PYTHON_ALLOWED_EXECUTABLES_PROPERTY
                            + " must contain at least one absolute executable path");
        }
        Set<Path> allowedExecutables = new LinkedHashSet<>();
        for (String rawEntry : rawAllowlist.split(",")) {
            String entry = rawEntry.trim();
            if (entry.isEmpty()) {
                continue;
            }
            Path path = Paths.get(entry);
            if (!path.isAbsolute()) {
                throw new IllegalStateException(
                        "Python source allowlist entry must be an absolute path: " + entry);
            }
            allowedExecutables.add(normalize(path));
        }
        if (allowedExecutables.isEmpty()) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set the JVM system property, e.g. -Dpython.allowed.executables=/usr/bin/python3,/opt/venv/bin/python
2. Verify with: java -XshowSettings:properties -version 2>&1 | grep python.allowed
3. If running via seatunnel.sh, add the property to JVM options in the worker startup config

Example fix

// before
java -jar seatunnel-starter.jar
// after
java -Dpython.allowed.executables=/usr/bin/python3 -jar seatunnel-starter.jar

String v = System.getProperty("python.allowed.executables", "");
if (v.trim().isEmpty()) throw new IllegalStateException("Set -Dpython.allowed.executables=/abs/path/python3 before starting SeaTunnel");

When it happens

Trigger: Calling PythonSourceExecutionPolicy.allowedExecutables() (indirectly via source open) when System.getProperty for the allowlist returns empty/whitespace, e.g. the property was never set via -Dpython.allowed.executables=...

Common situations: Deploying a Zeta worker or running a batch job without the -D flag in JVM options; copying config from docs that omit the property; running unit tests without the system property set.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Python source allowlist entry must be an absolute path: {}
• Server property {} does not contain a usable absolute path
• deploy mode not support : ${MODE}
• Unable to resolve python.executable from PATH: {}
• python.executable must be an absolute path or a bare command

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