apache/incubator-seata · error · StoreException

The driver {%s} cannot be found in the path %s. Please ensur

Error message

The driver {%s} cannot be found in the path %s. Please ensure that the appropriate database driver dependencies are included in the classpath.

What it means

In AbstractDataSourceProvider.validate(), after loader.loadClass(driverClassName) throws ClassNotFoundException, Seata enumerates the folders on loader.path/java.class.path (for MySQL drivers it specifically looks for a jdbc/ subfolder) and rethrows StoreException naming the driver and every searched path. It tells you the driver jar is not where Seata looks for it.

Source

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

            }
            String driverClassPath = Stream.of(folderPath.split(File.pathSeparator))
                    .map(File::new)
                    .filter(File::exists)
                    .map(file -> file.isFile() ? file.getParentFile() : file)
                    .filter(Objects::nonNull)
                    .filter(File::isDirectory)
                    // Only the MySQL driver needs to be placed in the jdbc folder.
                    .map(file -> (MYSQL8_DRIVER_CLASS_NAME.equals(driverClassName)
                                    || MYSQL_DRIVER_CLASS_NAME.equals(driverClassName))
                            ? new File(file, "jdbc")
                            : file)
                    .filter(File::exists)
                    .filter(File::isDirectory)
                    .distinct()
                    .findAny()
                    .map(File::getAbsolutePath)
                    .orElseThrow(() -> new ShouldNeverHappenException("cannot find jdbc folder"));
            throw new StoreException(String.format(
                    "The driver {%s} cannot be found in the path %s. Please ensure that the appropriate database driver dependencies are included in the classpath.",
                    driverClassName, driverClassPath));
        }
    }
    /**
     * generate the datasource
     * @return datasource
     */
    public abstract DataSource doGenerate();

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

View on GitHub (pinned to e01f97c6db)

Solutions

1. Copy the matching driver jar into the seata-server jdbc/ folder for MySQL/MariaDB (message's path tells you the exact expected location), or into lib/ for other databases.
2. For application-embedded use, add the driver as a runtime dependency: e.g. `mysql:mysql-connector-java` (or `com.mysql:mysql-connector-j`).
3. Verify store.db.driver-class-name matches the jar's actual class (com.mysql.cj.jdbc.Driver for Connector/J 8.x vs com.mysql.jdbc.Driver for 5.x).
4. Restart the server after adding the jar — drivers are resolved at datasource generation, not lazily.

Example fix

# before
# store.db.driver-class-name = com.mysql.cj.jdbc.Driver
# seata-server/jdbc/ empty -> StoreException: The driver {com.mysql.cj.jdbc.Driver} cannot be found...

# after
cp mysql-connector-j-8.0.33.jar /path/to/seata-server/jdbc/
# then restart seata-server

// startup check: can the configured loader actually see the driver?
String driver = config.get("store.db.driver-class-name");
try {
    Class.forName(driver, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("JDBC driver " + driver + " not on classpath - add the jar to lib/ (MySQL: jdbc/) before starting", e);
}

try {
    provider.generate();
} catch (StoreException e) {
    if (e.getMessage() != null && e.getMessage().contains("cannot be found in the path")) {
        // deploy-time problem: copy the driver jar to the path printed in the message, restart
        throw new DeploymentException(e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: store.db.driver-class-name configured (e.g. com.mysql.cj.jdbc.Driver) but the jar is absent from the seata-server lib directory / your app classpath; for MySQL specifically, the jar is not inside the jdbc/ folder that the distribution expects.

Common situations: Fresh seata-server install where the user forgot to copy mysql-connector into jdbc/; docker image slimmed of drivers; switching dbType from file to db in store config without adding the corresponding driver dependency; driver jar present but for a different/GPL-optional reason excluded from packaging.

Related errors

• the {%s} can't be empty
• class loader set error, you should not use the Bootstrap cla
• unknown dbType:%s
• No JsonCodec provider found. Please add json-common-core to
• not found service provider for : {}

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