apache/seatunnel · error · ConfigCheckException

${validationMode} failed: ${message}

Error message

${validationMode} failed: ${message}

What it means

SeaTunnelConfValidateCommand.execute catches exceptions raised while validating a config under --dry-run and rethrows them as ConfigCheckException with the message '<validationMode> failed: <message>', where validationMode is 'Connectivity check' (DryRun.CONNECT) or 'Static analysis'. For CONNECT mode the message is additionally passed through DryRunConnectFailureMessageSanitizer before wrapping. The original exception is attached except in the sanitized CONNECT branch.

Source

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

            if (clientCommandArgs.getDryRun() == DryRun.CONNECT) {
                new DryRunConnectValidator(
                                sourceConfigs,
                                transformConfigs,
                                sinkConfigs,
                                sourceAndTransformClassLoader,
                                sinkClassLoader)
                        .validate();
            }

        } catch (Exception e) {
            String validationMode =
                    clientCommandArgs.getDryRun() == DryRun.CONNECT
                            ? "Connectivity check"
                            : "Static analysis";
            String message = e.getMessage();
            if (clientCommandArgs.getDryRun() == DryRun.CONNECT) {
                message = DryRunConnectFailureMessageSanitizer.sanitize(message);
                throw new ConfigCheckException(validationMode + " failed: " + message);
            }
            throw new ConfigCheckException(validationMode + " failed: " + message, e);
        }
    }

    /**
     * Validate the configuration and return a reusable result for non-CLI integrations.
     *
     * <p>The result is deliberately config-level and does not claim runtime-equivalent validation.
     */
    public ConfigValidationResult validateResult() {
        try {
            execute();
            return ConfigValidationResult.success(validationPhase());
        } catch (ConfigCheckException e) {
            String message = e.getMessage();
            String prefix = validationMode() + " failed: ";
            if (message != null && message.startsWith(prefix)) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the <message> after 'failed:' — it names the plugin and the specific validation problem.
2. Fix the config issue indicated (schema mismatch, missing upstream, failed connectivity) and re-run the dry run.
3. If the sanitizer stripped details needed for debugging, re-run with the raw engine logs or STATIC mode to see the full exception.
4. Validate connector option names against the connector's documentation/option rules.

// run the dry-run in CI and parse the wrapped message to route failures
// seatunnel.sh --config job.conf --dry-run CONNECT || handle_failure

try { validateConf(conf, dryRun); } catch (ConfigCheckException e) { String msg = e.getMessage(); if (msg.startsWith("Connectivity check failed:")) { handleConnectivity(msg); } else if (msg.startsWith("Static analysis failed:")) { handleStatic(msg); } else { throw e; } }

When it happens

Trigger: Running with --dry-run CONNECT or STATIC when the underlying validation throws — e.g. any of the ConfigCheckExceptions from DryRunConnectValidator (2564-2567), a connector factory instantiation failure, or a config parse error during static analysis.

Common situations: Pre-submit config validation in CI; developers checking connectivity of source/sink options; configs with schema mismatches or missing upstreams (see related errors); invalid plugin names that fail factory lookup.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• ${location(SOURCE, configIndex, factoryId)} did not infer an
• No upstream source or transform is available for sink.
• The SQL config must contain at least one source table
• The SQL config must contain `INSERT INTO ... SELECT ...` syn
• Table name duplicate: %s

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