{"record":{"id":"e0f0b0620232006b","repo":"apache/incubator-seata","slug":"the-driver-s-cannot-be-found-in-the-path-s-pl","errorCode":null,"errorMessage":"The driver {%s} cannot be found in the path %s. Please ensure that the appropriate database driver dependencies are included in the classpath.","messagePattern":"The driver (.+?) cannot be found in the path (.+?)\\. Please ensure that the appropriate database driver dependencies are included in the classpath\\.","errorType":"exception","errorClass":"StoreException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/seata/core/store/db/AbstractDataSourceProvider.java","lineNumber":119,"sourceCode":"            }\n            String driverClassPath = Stream.of(folderPath.split(File.pathSeparator))\n                    .map(File::new)\n                    .filter(File::exists)\n                    .map(file -> file.isFile() ? file.getParentFile() : file)\n                    .filter(Objects::nonNull)\n                    .filter(File::isDirectory)\n                    // Only the MySQL driver needs to be placed in the jdbc folder.\n                    .map(file -> (MYSQL8_DRIVER_CLASS_NAME.equals(driverClassName)\n                                    || MYSQL_DRIVER_CLASS_NAME.equals(driverClassName))\n                            ? new File(file, \"jdbc\")\n                            : file)\n                    .filter(File::exists)\n                    .filter(File::isDirectory)\n                    .distinct()\n                    .findAny()\n                    .map(File::getAbsolutePath)\n                    .orElseThrow(() -> new ShouldNeverHappenException(\"cannot find jdbc folder\"));\n            throw new StoreException(String.format(\n                    \"The driver {%s} cannot be found in the path %s. Please ensure that the appropriate database driver dependencies are included in the classpath.\",\n                    driverClassName, driverClassPath));\n        }\n    }\n    /**\n     * generate the datasource\n     * @return datasource\n     */\n    public abstract DataSource doGenerate();\n\n    /**\n     * Get db type db type.\n     *\n     * @return the db type\n     */\n    protected DBType getDBType() {\n        return DBType.valueof(CONFIG.getConfig(ConfigurationKeys.STORE_DB_TYPE));\n    }","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/store/db/AbstractDataSourceProvider.java#L101-L137","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","For application-embedded use, add the driver as a runtime dependency: e.g. `mysql:mysql-connector-java` (or `com.mysql:mysql-connector-j`).","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).","Restart the server after adding the jar — drivers are resolved at datasource generation, not lazily."],"exampleFix":"# before\n# store.db.driver-class-name = com.mysql.cj.jdbc.Driver\n# seata-server/jdbc/ empty -> StoreException: The driver {com.mysql.cj.jdbc.Driver} cannot be found...\n\n# after\ncp mysql-connector-j-8.0.33.jar /path/to/seata-server/jdbc/\n# then restart seata-server","handlingStrategy":"validation","validationCode":"// startup check: can the configured loader actually see the driver?\nString driver = config.get(\"store.db.driver-class-name\");\ntry {\n    Class.forName(driver, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"JDBC driver \" + driver + \" not on classpath - add the jar to lib/ (MySQL: jdbc/) before starting\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    provider.generate();\n} catch (StoreException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"cannot be found in the path\")) {\n        // deploy-time problem: copy the driver jar to the path printed in the message, restart\n        throw new DeploymentException(e.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Make 'driver jar present' part of the deployment checklist for store.mode=db.","For MySQL, always use the jdbc/ folder of seata-server as documented.","Add a CI step that Class.forName()s the configured driver inside the packaged artifact."],"tags":["jdbc","driver","classpath","store","mysql","configuration"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}