What causes "datasource required not null!" in apache/incubator-seata?

Call setDataSource(...) on the DbStateMachineConfig bean before the context refreshes.

apache/incubator-seata · critical · IllegalArgumentException

datasource required not null!

Error message

datasource required not null!

What it means

Thrown by DbStateMachineConfig.afterPropertiesSet (Spring InitializingBean callback) when the Saga state machine config bean is initialized without a DataSource. The DB-backed Saga engine needs a database for state-log storage, so a missing datasource is a fatal wiring error at startup.

Source

Thrown at compatible/src/main/java/io/seata/saga/engine/config/DbStateMachineConfig.java:113

    /**
     * Gets db type from data source.
     *
     * @param dataSource the data source
     * @return the db type from data source
     * @throws SQLException the sql exception
     */
    public static String getDbTypeFromDataSource(DataSource dataSource) throws SQLException {
        try (Connection con = dataSource.getConnection()) {
            DatabaseMetaData metaData = con.getMetaData();
            return metaData.getDatabaseProductName();
        }
    }

    @Override
    public void afterPropertiesSet() throws Exception {
        if (dataSource == null) {
            throw new IllegalArgumentException("datasource required not null!");
        }

        dbType = getDbTypeFromDataSource(dataSource);
        if (getStateLogStore() == null) {
            DbAndReportTcStateLogStore dbStateLogStore = new DbAndReportTcStateLogStore();
            dbStateLogStore.setDataSource(dataSource);
            dbStateLogStore.setTablePrefix(tablePrefix);
            dbStateLogStore.setDbType(dbType);
            dbStateLogStore.setDefaultTenantId(getDefaultTenantId());
            dbStateLogStore.setSeqGenerator(getSeqGenerator());

            if (StringUtils.hasLength(getSagaJsonParser())) {
                ParamsSerializer paramsSerializer = new ParamsSerializer();
                paramsSerializer.setJsonParserName(getSagaJsonParser());
                dbStateLogStore.setParamsSerializer(paramsSerializer);
            }

            if (sagaTransactionalTemplate == null) {

View on GitHub (pinned to e01f97c6db)

Solutions

Call setDataSource(...) on the DbStateMachineConfig bean before the context refreshes.
Check the property/placeholder that supplies the datasource actually resolves (no typo, profile active).
In XML config verify <property name="dataSource" ref="..."/> points at an existing bean.
Ensure afterPropertiesSet is not invoked manually before wiring is complete.

Example fix

// before
@Bean
public DbStateMachineConfig dbStateMachineConfig() {
    DbStateMachineConfig cfg = new DbStateMachineConfig();
    // datasource never set -> afterPropertiesSet throws
    return cfg;
}

// after
@Bean
public DbStateMachineConfig dbStateMachineConfig(DataSource dataSource) {
    DbStateMachineConfig cfg = new DbStateMachineConfig();
    cfg.setDataSource(dataSource);
    return cfg;
}

Defensive patterns

Strategy: validation

Validate before calling

DbStateMachineConfig cfg = new DbStateMachineConfig();
Objects.requireNonNull(dataSource, "DataSource must be wired before DbStateMachineConfig init");
cfg.setDataSource(dataSource);

Try / catch

try {
    context.refresh();
} catch (BeanInitializationException e) {
    if (e.getCause() instanceof IllegalArgumentException
            && String.valueOf(e.getCause().getMessage()).contains("datasource")) {
        throw new ConfigurationException("DbStateMachineConfig is missing its dataSource bean/property", e);
    }
    throw e;
}

Prevention

Wire the DataSource in the same @Bean method that constructs DbStateMachineConfig.
Add a startup assertion Objects.requireNonNull(dataSource) with a helpful message.
Validate datasource property placeholders (name, profile) before context refresh.

When it happens

Trigger: Creating a DbStateMachineConfig bean (via XML or @Bean) without calling setDataSource(...), or the datasource property placeholder resolving to null; also programmatic construction where afterPropertiesSet is invoked before the datasource is assigned.

Common situations: Spring Boot autoconfig partially overridden so the setDataSource call is dropped; property name typo (dataSource vs datasource) leaving the setter uncalled; test contexts building the config manually; migrating from in-memory to DB state log store and forgetting the datasource bean.

Related errors

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/73dbe19677ec503b. Report an issue: GitHub.