apache/seatunnel · error · IllegalArgumentException

Plugin type must be one of: [source, sink, transform]

Error message

Plugin type must be one of: [source, sink, transform]

What it means

MetadataExportCommandArgs.PluginTypeConverter converts the --plugin-type CLI argument to the PluginType enum via PluginType.valueOf on the uppercased value. If the user supplies any string that is not exactly source, sink, or transform (case-insensitive), the IllegalArgumentException from valueOf is rethrown with a message listing the allowed values. It exists to give a clear CLI-level message instead of a raw enum stack trace.

Source

Thrown at seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/args/MetadataExportCommandArgs.java:76

    private boolean prettyPrint = true;

    @Parameter(
            names = {"--stdout"},
            description = "Write JSON to stdout instead of a file")
    private boolean stdout = false;

    @Override
    public Command<?> buildCommand() {
        return new MetadataExportCommand(this);
    }

    public static class PluginTypeConverter implements IStringConverter<PluginType> {
        @Override
        public PluginType convert(String value) {
            try {
                return PluginType.valueOf(value.toUpperCase());
            } catch (IllegalArgumentException e) {
                throw new IllegalArgumentException(
                        "Plugin type must be one of: [source, sink, transform]");
            }
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set --plugin-type to exactly one of source, sink, or transform (case-insensitive).
2. Check for hidden whitespace or plural forms in scripts passing the value.
3. Run with --help on the metadata export command to see the documented flag values.

Example fix

// before
seatunnel.sh -m --plugin-type reader
// after
seatunnel.sh -m --plugin-type source

const VALID = ["source", "sink", "transform"];
if (!VALID.includes(pluginType.trim().toLowerCase())) {
  throw new Error("plugin-type must be one of: " + VALID.join(", "));
}

function isPluginType(v) { return ["source","sink","transform"].includes(v.trim().toLowerCase()); }

try { runExport(args); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Plugin type must be")) { System.err.println("Fix --plugin-type: " + e.getMessage()); } else { throw e; } }

When it happens

Trigger: Running the metadata export command (e.g. seatunnel.sh -m) with --plugin-type set to a value other than source/sink/transform, such as 'Source ', 'sources', 'reader', or a typo like 'sourc'. JCommander invokes the converter during argument parsing, before the command executes.

Common situations: Typo in the CLI flag value; assuming case or plural forms matter; copying plugin-type values from connector configs where other names exist; scripting with a variable that contains an unexpected value.

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

• Unsupported dry-run mode '${value}'. Currently only [static,
• SeaTunnel job on st-engine submitted target only support the
• The plugin type of seaTunnel only support these options: [so
• Unsupported checkpoint history status %s
• Invalid --status ${status}; expected PENDING, SENDING, ACKED

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