apache/seatunnel · error · FactoryException

Unable to create a sink for identifier '${factoryIdentifier}

Error message

Unable to create a sink for identifier '${factoryIdentifier}'.

What it means

FactoryUtil.createAndPrepareSink wraps any Throwable raised while discovering, instantiating, or preparing a Sink in a FactoryException with this message. The underlying cause attached to the exception carries the actual failure reason.

Source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/table/factory/FactoryUtil.java:262

            }

            TableSinkFactoryContext context =
                    TableSinkFactoryContext.replacePlaceholderAndCreate(
                            catalogTable,
                            config,
                            classLoader,
                            tableSinkFactory.excludeTablePlaceholderReplaceKeys());
            ConfigValidator.of(context.getOptions()).validate(tableSinkFactory.optionRule());

            LOG.info(
                    "Create sink '{}' with upstream input catalog-table[database: {}, schema: {}, table: {}]",
                    factoryIdentifier,
                    catalogTable.getTablePath().getDatabaseName(),
                    catalogTable.getTablePath().getSchemaName(),
                    catalogTable.getTablePath().getTableName());
            return tableSinkFactory.createSink(context).createSink();
        } catch (Throwable t) {
            throw new FactoryException(
                    String.format(
                            "Unable to create a sink for identifier '%s'.", factoryIdentifier),
                    t);
        }
    }

    public static <IN, StateT, CommitInfoT, AggregatedCommitInfoT>
            SeaTunnelSink<IN, StateT, CommitInfoT, AggregatedCommitInfoT> createMultiTableSink(
                    Map<TablePath, SeaTunnelSink> sinks,
                    ReadonlyConfig options,
                    ClassLoader classLoader) {
        try {
            TableSinkFactory<IN, StateT, CommitInfoT, AggregatedCommitInfoT> factory =
                    new MultiTableSinkFactory();
            MultiTableFactoryContext context =
                    new MultiTableFactoryContext(options, classLoader, sinks);
            ConfigValidator.of(context.getOptions()).validate(factory.optionRule());
            return factory.createSink(context).createSink();

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect the exception cause to find the real error inside sink creation.
Confirm the sink identifier (e.g. 'Jdbc', 'Console') matches an installed plugin exactly.
Deploy the sink connector jar to every node's connectors directory.
Check sink option names/required options against the connector docs.

Example fix

// before
sink {
  Jdbc-Sink {
    url = "jdbc:mysql://localhost/test"
  }
}
// after
sink {
  Jdbc {
    url = "jdbc:mysql://localhost/test"
    driver = "com.mysql.cj.jdbc.Driver"
  }
}

Defensive patterns

Strategy: try-catch

Validate before calling

Optional<TableSinkFactory> f = FactoryUtil.discoverOptionalSinkFactory(classLoader, pluginId);
if (!f.isPresent()) {
    throw new IllegalArgumentException("Sink plugin not installed: " + pluginId);
}

Try / catch

try {
    sink = FactoryUtil.createAndPrepareSink(catalogTable, cfg, classLoader, pluginId);
} catch (FactoryException e) {
    LOG.error("Sink '{}' creation failed: {}", pluginId, e.getCause());
    throw e;
}

Prevention

Pre-validate sink options against the factory's optionRule.
Deploy sink connector jars to every node before submitting jobs.
Match identifiers exactly as documented (case-insensitive but spelling matters).

When it happens

Trigger: Calling FactoryUtil.createAndPrepareSink with a sink identifier whose factory is absent from the classpath, whose createSink()/prepare() throws, whose option validation fails, or whose table path conversion fails.

Common situations: Misspelled sink plugin name in the config; sink connector jar not deployed on all nodes; sink prepare() fails on bad connection settings or invalid table schema mapping.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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