apache/seatunnel · error · JobDefineCheckException

The '%s' option configured is incorrect, this table(%s) belo

Error message

The '%s' option configured is incorrect, this table(%s) belonging to source/transform(%s) is not used.

What it means

checkLinked ensures every source/transform vertex in a complex graph is consumed (its VertexStatus is marked from CREATED). If a vertex's output table id is never referenced by any downstream plugin_input, JobDefineCheckException is thrown saying the table is unused. Every produced table must be linked into the pipeline.

Source

Thrown at seatunnel-engine/seatunnel-engine-core/src/main/java/org/apache/seatunnel/engine/core/parse/ConfigParserUtil.java:222

                                    (id, old) -> {
                                        if (old == null) {
                                            throw new JobDefineCheckException(
                                                    String.format(
                                                            "The '%s' option configured in [%s] is incorrect, and the source/transform[%s] is not found.",
                                                            PLUGIN_INPUT.key(),
                                                            config.getString(PLUGIN_NAME.key()),
                                                            id));
                                        }
                                        return new Tuple2<>(old._1(), VertexStatus.LINKED);
                                    }));
        }
    }

    private static void checkLinked(Map<String, Tuple2<Config, VertexStatus>> vertexStatusMap) {
        vertexStatusMap.forEach(
                (id, vertex) -> {
                    if (vertex._2() == VertexStatus.CREATED) {
                        throw new JobDefineCheckException(
                                String.format(
                                        "The '%s' option configured is incorrect, this table(%s) belonging to source/transform(%s) is not used.",
                                        PLUGIN_INPUT.key(),
                                        id,
                                        vertex._1().getString(PLUGIN_NAME.key())));
                    }
                });
    }

    private static void checkExistTableId(List<? extends Config> configs) {
        for (Config config : configs) {
            if (!ReadonlyConfig.fromConfig(config).getOptional(PLUGIN_OUTPUT).isPresent()) {
                throw new JobDefineCheckException(
                        String.format(
                                "The source/transform(%s) is not configured with '%s' option",
                                config.getString(PLUGIN_NAME.key()), PLUGIN_OUTPUT.key()),
                        new OptionValidationException(PLUGIN_OUTPUT));
            }

View on GitHub (pinned to cf67b549a7)

Solutions

Add or fix a downstream plugin whose plugin_input references the unused table id
Remove the orphan source/transform block if its output is no longer needed
Match the error's table id to find the unused producer in the config
Verify each plugin_output has at least one matching plugin_input

Example fix

// before
source { FakeSource { plugin_output = "t1" } }
sink { Console { plugin_input = "t2" } }
// after
source { FakeSource { plugin_output = "t1" } }
sink { Console { plugin_input = "t1" } }

Defensive patterns

Strategy: validation

Validate before calling

Set<String> consumed = collectPluginInputs(config);
for (String out : collectPluginOutputs(config)) {
    if (!consumed.contains(out)) {
        throw new IllegalArgumentException("Unused table id: " + out);
    }
}

Try / catch

try {
    ConfigParserUtil.checkLinked(...);
} catch (JobDefineCheckException e) {
    log.error("Unlinked vertex: {}", e.getMessage());
    throw e;
}

Prevention

Every plugin_output must have a downstream consumer
Remove orphan producers when deleting branches
Draw the DAG on paper before writing multi-table configs
Validate with checkGraph in CI

When it happens

Trigger: A source/transform declares plugin_output but no downstream transform/sink references that id via plugin_input; detected in checkComplexGraph via checkLinked after all edges are resolved.

Common situations: Deleting the downstream sink/transform but leaving the orphan producer; renaming the consumer's plugin_input without updating the producer; intentionally disabled branch still emitting a table id.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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