apache/incubator-seata · error · StoreException

the {%s} can't be empty

Error message

the {%s} can't be empty

What it means

AbstractDataSourceProvider.getDriverClassName() reads config key store.db.driver-class-name (ConfigurationKeys.STORE_DB_DRIVER_CLASS_NAME); if the value is blank it throws StoreException naming the key with 'the {store.db.driver-class-name} can't be empty'. This is a hard prerequisite check before any DataSource for store mode db can be built.

Source

Thrown at core/src/main/java/org/apache/seata/core/store/db/AbstractDataSourceProvider.java:147

    /**
     * Get db type db type.
     *
     * @return the db type
     */
    protected DBType getDBType() {
        return DBType.valueof(CONFIG.getConfig(ConfigurationKeys.STORE_DB_TYPE));
    }

    /**
     * get db driver class name
     *
     * @return the db driver class name
     */
    protected String getDriverClassName() {
        String driverClassName = CONFIG.getConfig(ConfigurationKeys.STORE_DB_DRIVER_CLASS_NAME);
        if (StringUtils.isBlank(driverClassName)) {
            throw new StoreException(
                    String.format("the {%s} can't be empty", ConfigurationKeys.STORE_DB_DRIVER_CLASS_NAME));
        }
        return driverClassName;
    }

    /**
     * get db max wait
     *
     * @return the db max wait
     */
    protected Long getMaxWait() {
        return CONFIG.getLong(ConfigurationKeys.STORE_DB_MAX_WAIT, DEFAULT_DB_MAX_WAIT);
    }

    protected ClassLoader getDriverClassLoader() {
        return DRIVER_LOADERS.getOrDefault(getDriverClassName(), this.getClass().getClassLoader());
    }

View on GitHub (pinned to e01f97c6db)

Solutions

1. Set the key in the server config: e.g. `store.db.driver-class-name: com.mysql.cj.jdbc.Driver` (match your DB: org.postgresql.Driver, oracle.jdbc.driver.OracleDriver, etc.).
2. Check YAML indentation / file.conf block so the key truly sits under store.db.
3. Confirm the other mandatory store.db keys (url, user; and usually password) are also set to avoid the follow-up 'can't be empty' errors.
4. If you did not intend DB storage, set store.mode back to file (or db+raft where applicable) so the provider is not invoked.

Example fix

# before (application.yml)
seata:
  store:
    mode: db
    db:
      url: jdbc:mysql://...   # driver-class-name missing -> StoreException

# after
seata:
  store:
    mode: db
    db:
      driver-class-name: com.mysql.cj.jdbc.Driver
      url: jdbc:mysql://127.0.0.1:3306/seata
      user: seata
      password: seata

// startup config validation
String driver = seataConfig.get("store.db.driver-class-name");
if (storeMode.equals("db") && (driver == null || driver.trim().isEmpty())) {
    throw new ConfigurationException("store.db.driver-class-name is required when store.mode=db");
}

try {
    dataSourceProvider.generate();
} catch (StoreException e) {
    if (e.getMessage() != null && e.getMessage().contains("can't be empty")) {
        throw new ConfigurationException("Missing mandatory store.db key: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: store.mode=db configured on the server (or a DataSourceProvider used by a client/embedded component) while store.db.driver-class-name is missing, empty, or whitespace in file.conf/application.yml/registry config.

Common situations: Switching store.mode from file to db but only setting url/user/password; config keys misspelled or nested under the wrong block after a 1.x->2.x conf migration; YAML indentation putting the key outside the store.db section.

Related errors

• class loader set error, you should not use the Bootstrap cla
• The driver {%s} cannot be found in the path %s. Please ensur
• could not convert '{size}' to byte length
• {dataName} data is too large, size={length}
• Unknown BranchType[{name}]

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