apache/seatunnel · error · IllegalArgumentException

Unknown ftp connection mode: ${mode}

Error message

Unknown ftp connection mode: ${mode}

What it means

FtpConnectionMode.fromMode() converts the user-supplied 'ftp.connection.mode' string into the FtpConnectionMode enum by matching against known modes (e.g. ACTIVE_LOCAL, PASSIVE_LOCAL...). If no enum constant matches after lowercasing, it throws IllegalArgumentException. This is a strict configuration-value validation guard.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-ftp/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/ftp/system/FtpConnectionMode.java:45

    PASSIVE_LOCAL("passive_local");

    private final String mode;

    FtpConnectionMode(String mode) {
        this.mode = mode;
    }

    public String getMode() {
        return mode;
    }

    public static FtpConnectionMode fromMode(String mode) {
        for (FtpConnectionMode ftpConnectionModeEnum : FtpConnectionMode.values()) {
            if (ftpConnectionModeEnum.getMode().equals(mode.toLowerCase())) {
                return ftpConnectionModeEnum;
            }
        }
        throw new IllegalArgumentException("Unknown ftp connection mode: " + mode);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Print the configured value and compare against the FtpConnectionMode enum constants (the valid mode strings)
2. Fix the ftp.connection.mode value in the job config to an exactly supported name (matching is case-insensitive)
3. Check the connector version's FtpConnectionMode source for the exact list of accepted modes

Example fix

// before
"ftp.connection.mode" = "passive-mode"
// after
"ftp.connection.mode" = "passive" // must match FtpConnectionMode.getMode() exactly (case-insensitive)

Set<String> valid = Arrays.stream(FtpConnectionMode.values())
    .map(FtpConnectionMode::getMode).collect(Collectors.toSet());
if (!valid.contains(mode.toLowerCase())) throw new IllegalArgumentException(
    "ftp.connection.mode must be one of " + valid + ", got: " + mode);

try {
    FtpConnectionMode m = FtpConnectionMode.fromMode(mode);
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("Bad ftp.connection.mode: " + mode + ", valid: "
        + Arrays.toString(FtpConnectionMode.values()));
}

When it happens

Trigger: Calling fromMode with any string not equal (case-insensitively) to one of the supported mode names — typically from a typo in the 'ftp.connection.mode' config option.

Common situations: Misspelled mode in the SeaTunnel job config (e.g. 'passive' instead of the exact enum name); uppercase-only assumption if the value isn't normalized before this call; copied config from an older/newer connector version with renamed modes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown format type:
• input.on-error must be "skip" or "fail".
• input.multiline.match must be "after" or "before".
• input.output-format.type must be "line" or "json".
• Unsupported agent.delivery-guarantee: ${value}. Supported: B

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