apache/seatunnel · error · ConfigCheckException

Plugin name is required but missing

Error message

Plugin name is required but missing

What it means

Each plugin block in a SeaTunnel config must declare a `plugin_name` identifying which Source/Transform/Sink factory to instantiate. validatePluginConfigs throws this ConfigCheckException when a plugin config's plugin_name is absent or blank, before factory discovery is attempted. It fails fast so the user knows which structural requirement of the config is unmet.

Solutions

1. Add `plugin_name = "<PluginName>"` to every source/transform/sink block in the config
2. Verify the key is spelled exactly `plugin_name` (not `name` or `plugin`)
3. Check for stray empty plugin blocks `{}` left in the config file
4. Validate locally with `seatunnel.sh --validate ...` before submitting

Example fix

// before
source {
  {
    url = "jdbc:mysql://localhost:3306/test"
  }
}
// after
source {
  Jdbc {
    url = "jdbc:mysql://localhost:3306/test"
    driver = "com.mysql.cj.jdbc.Driver"
    plugin_name = "Jdbc"
  }
}

for (Config pluginConfig : pluginConfigs) {
    String name = ReadonlyConfig.fromConfig(pluginConfig).getOptional(PLUGIN_NAME).orElse(null);
    if (name == null || name.trim().isEmpty()) {
        throw new IllegalArgumentException("Each plugin block requires a non-empty plugin_name");
    }
}

try {
    validatePluginConfigs(...);
} catch (ConfigCheckException e) {
    if (e.getMessage().contains("Plugin name is required")) {
        log.error("A source/transform/sink block is missing plugin_name");
    }
}

When it happens

Trigger: A source/transform/sink block in the job config has no `plugin_name` option, or it is set to an empty/whitespace string; validatePluginConfigs iterates the parsed plugin configs and finds one blank.

Common situations: Hand-edited HOCON configs where the plugin_name line was deleted, programmatically generated configs omitting the field, or renaming the key to something like `name` instead of `plugin_name`.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• All candidate sink tables were skipped during job parsing.
• AmazonDocumentDB option 'uri' must include authentication…
• batch_size must be >= 1, got:
• Binary chunk size must be positive, got
• Binary chunk size too large (max 100MB), got

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

Appendix: source

Thrown at seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/command/SeaTunnelConfValidateCommand.java:317

     * <p>The caller is responsible for setting {@code pluginClassLoader} as the thread context
     * classloader before calling this method so that {@link FactoryUtil#discoverFactory} resolves
     * the correct factories.
     *
     * @param pluginConfigs raw plugin {@link Config} blocks to validate
     * @param factoryClass the factory interface to discover (source / transform / sink)
     * @param pluginClassLoader the classloader with the connector JARs on its search path
     */
    private void validatePluginConfigs(
            List<? extends Config> pluginConfigs,
            Class<? extends Factory> factoryClass,
            ClassLoader pluginClassLoader)
            throws ConfigCheckException {
        for (Config pluginConfig : pluginConfigs) {
            ReadonlyConfig readonlyConfig = ReadonlyConfig.fromConfig(pluginConfig);
            String pluginName = readonlyConfig.getOptional(PLUGIN_NAME).orElse("");

            if (StringUtils.isBlank(pluginName)) {
                throw new ConfigCheckException("Plugin name is required but missing");
            }

            Factory factory =
                    FactoryUtil.discoverFactory(pluginClassLoader, factoryClass, pluginName);

            ConfigValidator.of(readonlyConfig).validate(factory.optionRule());
            validateOptionTypes(readonlyConfig, factory.optionRule());
            ConfigValidator.validateUnknownKeys(readonlyConfig, factory.optionRule(), pluginName);

            if ("Sql".equalsIgnoreCase(pluginName)
                    && TableTransformFactory.class.isAssignableFrom(factoryClass)) {
                validateSqlTransformSyntax(pluginConfig, pluginClassLoader);
            }
        }
    }

    private void validateSqlTransformSyntax(Config pluginConfig, ClassLoader pluginClassLoader)
            throws ConfigCheckException {

View on GitHub (pinned to cf67b549a7)