Unsupported FTP connection mode

Error message

Unsupported FTP connection mode: ${mode}, Using default FTP connection mode: ${FtpConnectionMode.ACTIVE_LOCAL.getMode()}

What it means

setFsFtpConnectionMode parses the configured connection-mode string via FtpConnectionMode.fromMode and switches on the result. Any mode that falls into the default branch (an unrecognized value) logs this warning and silently falls back to local active mode instead of failing the job. It is a configuration-typo diagnostic, not an exception.

Solutions

Inspect the config value of fs.ftp.connection-mode and set it to exactly one of the FtpConnectionMode values: the mode strings returned by FtpConnectionMode.getMode() (e.g. passive_local / active_local).
If unsure, remove the option to let the connector use its default behavior.
Check FtpConnectionMode.fromMode to confirm whether the value is case-sensitive and normalize the config accordingly.

Example fix

// before
fs.ftp.connection-mode = PASSIVE
// after
fs.ftp.connection-mode = passive_local

Defensive patterns

Strategy: validation

Validate before calling

// Validate the configured mode against FtpConnectionMode before submit:
String mode = config.getString("fs.ftp.connection-mode");
boolean valid = java.util.Arrays.stream(FtpConnectionMode.values())
        .anyMatch(m -> m.getMode().equalsIgnoreCase(mode));
if (!valid) {
    throw new IllegalArgumentException("fs.ftp.connection-mode must be one of "
        + java.util.Arrays.toString(FtpConnectionMode.values()) + " but was " + mode);
}

Prevention

Copy the mode string exactly from the FtpConnectionMode enum's getMode() values
Keep config values lowercase/consistent with what fromMode() expects
Validate FTP options in a pre-submit config check rather than discovering the fallback in logs

When it happens

Trigger: The fs.ftp.connection-mode option is set to a string that FtpConnectionMode.fromMode cannot resolve to PASSIVE_LOCAL or ACTIVE_LOCAL (typo, wrong casing if fromMode is case-sensitive, or an empty/placeholder value), causing the switch to hit its default branch during connect().

Common situations: Typo like 'pasv' or 'passive' instead of the exact enum string; copying a mode name from another FTP library; config key populated by templating with an unset variable; case mismatch between config and the enum's accepted values.

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

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

Appendix: source

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

                    }

                    LOG.info("Using active mode for FTP connection");
                } catch (IOException e) {
                    // if active mode failed, switch to passive mode
                    client.enterLocalPassiveMode();
                    // update the connection mode to passive mode
                    getConf()
                            .set(FS_FTP_CONNECTION_MODE, FtpConnectionMode.PASSIVE_LOCAL.getMode());
                } finally {
                    // delete the test directory if it was created
                    FTPFile[] files = client.listFiles(pathName);
                    if (files != null && files.length > 0) {
                        client.deleteFile(pathName);
                    }
                }
                break;
            default:
                log.warn(
                        "Unsupported FTP connection mode: " + mode,
                        " Using default FTP connection mode: "
                                + FtpConnectionMode.ACTIVE_LOCAL.getMode());
                client.enterLocalActiveMode();
                break;
        }
    }

    /**
     * Logout and disconnect the given FTPClient. *
     *
     * @param client FTPClient
     */
    void disconnect(FTPClient client) {
        if (client == null || !client.isConnected()) {
            return;
        }

View on GitHub (pinned to cf67b549a7)