apache/seatunnel · error · FactoryException

Unable to create a source for identifier '${factoryIdentifie

Error message

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

What it means

FactoryUtil.restoreAndPrepareSource wraps any Throwable raised while discovering, instantiating, or preparing a Source in a FactoryException with this message. It is a wrapper: the real cause (attached as the cause) explains what actually failed.

Source

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

                        CatalogTableUtil.convertDataTypeToCatalogTables(seaTunnelDataType, tableId);
            }
            LOG.info(
                    "get the CatalogTable from source {}: {}",
                    source.getPluginName(),
                    catalogTables.stream()
                            .map(CatalogTable::getTableId)
                            .map(TableIdentifier::toString)
                            .collect(Collectors.joining(",")));
            if (options.get(SourceConnectorCommonOptions.DAG_PARSING_MODE)
                    == ParsingMode.SHARDING) {
                CatalogTable catalogTable = catalogTables.get(0);
                catalogTables.clear();
                catalogTables.add(catalogTable);
            }
            return new Tuple2<>(source, catalogTables);

        } catch (Throwable t) {
            throw new FactoryException(
                    String.format(
                            "Unable to create a source for identifier '%s'.", factoryIdentifier),
                    t);
        }
    }

    private static <T, SplitT extends SourceSplit, StateT extends Serializable>
            SeaTunnelSource<T, SplitT, StateT> createAndPrepareSource(
                    TableSourceFactory factory,
                    ReadonlyConfig options,
                    ClassLoader classLoader,
                    MetadataConfig metaDataConfig) {
        TableSourceFactoryContext context =
                new TableSourceFactoryContext(options, classLoader, metaDataConfig);
        ConfigValidator.of(context.getOptions()).validate(factory.optionRule());
        TableSource<T, SplitT, StateT> tableSource = factory.createSource(context);
        return tableSource.createSource();
    }

View on GitHub (pinned to cf67b549a7)

Solutions

Read the 'Caused by' of the FactoryException — it contains the real failure.
Verify the factory identifier matches a Source plugin in the connectors directory (check plugin-mapping.properties).
Install the missing connector: sh bin/install-plugin.sh <version>.
Validate source options against the connector's documented option rule (missing required options fail in this path).

Example fix

// before
source {
  MySql-CDC-Jdbc {}
}
// after
source {
  JDBC {
    url = "jdbc:mysql://localhost:3306/db"
  }
}

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

try {
    Tuple2<SeaTunnelSource, List<CatalogTable>> t = FactoryUtil.createAndPrepareSource(cfg, classLoader, pluginId);
} catch (FactoryException e) {
    LOG.error("Source '{}' creation failed", pluginId, e.getCause()); // cause holds the real error
    throw e;
}

Prevention

Validate source options with ConfigValidator against the factory's optionRule before creating.
Keep connector jars in $SEATUNNEL_HOME/connectors and keep plugin-mapping.properties current.
Always log e.getCause() when handling FactoryException from createAndPrepareSource.

When it happens

Trigger: Calling FactoryUtil.createAndPrepareSource with a factory identifier whose Source plugin is missing, whose factory throws in its constructor/prepare(), whose options fail validation, or whose catalog table conversion fails.

Common situations: Typo in the source plugin name in the job config; connector jar not installed in $SEATUNNEL_HOME/connectors; connector throws during prepare() because of bad credentials or missing files.

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/92d0ddc9814ab29b. Report an issue: GitHub.