{"record":{"id":"6c4126ee947567ea","repo":"alibaba/canal","slug":"unable-to-load-com-mysql-jdbc-connectionimpl","errorCode":null,"errorMessage":"Unable to load com.mysql.jdbc.ConnectionImpl","messagePattern":"Unable to load com\\.mysql\\.jdbc\\.ConnectionImpl","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"dbsync/src/main/java/com/taobao/tddl/dbsync/binlog/DirectLogFetcher.java","lineNumber":196,"sourceCode":"\r\n            // Get underlying IO streams for network communications.\r\n            Object connIo = getDeclaredField(unwrapConn, connClazz, \"io\");\r\n            if (connIo == null) {\r\n                throw new IOException(\"Get null field:\" + conn.getClass().getName() + \"#io\");\r\n            }\r\n            mysqlOutput = (OutputStream) getDeclaredField(connIo, connIo.getClass(), \"mysqlOutput\");\r\n            mysqlInput = (InputStream) getDeclaredField(connIo, connIo.getClass(), \"mysqlInput\");\r\n\r\n            if (filePosition == 0) filePosition = BIN_LOG_HEADER_SIZE;\r\n            sendBinlogDump(fileName, filePosition, serverId, nonBlocking);\r\n            position = 0;\r\n        } catch (IOException e) {\r\n            close(); /* Do cleanup */\r\n            logger.error(\"Error on COM_BINLOG_DUMP: file = \" + fileName + \", position = \" + filePosition);\r\n            throw e;\r\n        } catch (ClassNotFoundException e) {\r\n            close(); /* Do cleanup */\r\n            throw new IOException(\"Unable to load com.mysql.jdbc.ConnectionImpl\", e);\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Put a byte in the buffer.\r\n     * \r\n     * @param b the byte to put in the buffer\r\n     */\r\n    protected final void putByte(byte b) {\r\n        ensureCapacity(position + 1);\r\n\r\n        buffer[position++] = b;\r\n    }\r\n\r\n    /**\r\n     * Put 16-bit integer in the buffer.\r\n     * \r\n     * @param i16 the integer to put in the buffer\r","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/dbsync/src/main/java/com/taobao/tddl/dbsync/binlog/DirectLogFetcher.java#L178-L214","documentation":"Thrown in DirectLogFetcher.open()'s catch(ClassNotFoundException) when Class.forName(\"com.mysql.jdbc.ConnectionImpl\") fails - the legacy driver class is not on the classpath. This is the canonical signal that the deployed mysql driver does not contain the old com.mysql.jdbc package.","triggerScenarios":"open() runs Class.forName(\"com.mysql.jdbc.ConnectionImpl\") and the JVM cannot resolve the class, so the catch block re-throws it as IOException(\"Unable to load com.mysql.jdbc.ConnectionImpl\", e).","commonSituations":"mysql-connector-java 8.0+ on the classpath, where the legacy com.mysql.jdbc.ConnectionImpl was removed (the com.mysql.cj.jdbc package replaces it); driver jar excluded from the build; an incompatible driver fork; classpath/shading stripped the class.","solutions":["Add mysql-connector-java 5.1.x to the classpath (it still ships com.mysql.jdbc.ConnectionImpl).","If you must use driver 8.x, switch to a dbsync/connector revision that loads com.mysql.cj.jdbc.JdbcConnection instead.","Verify with 'jar tf <driver>.jar | grep ConnectionImpl' whether the class is actually present.","Resolve classpath conflicts so only one driver version is present and the legacy class is loadable."],"exampleFix":"// before - driver 8.x on classpath, legacy class absent\nfetcher.open(conn, file, pos, serverId); // -> Unable to load com.mysql.jdbc.ConnectionImpl\n\n// after - pin a driver that still has the class\n<!-- pom.xml -->\n<dependency>\n  <groupId>mysql</groupId>\n  <artifactId>mysql-connector-java</artifactId>\n  <version>5.1.49</version>\n</dependency>","handlingStrategy":"validation","validationCode":"// Fail fast if the legacy driver class is absent\ntry { Class.forName(\"com.mysql.jdbc.ConnectionImpl\"); }\ncatch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"com.mysql.jdbc.ConnectionImpl missing - add mysql-connector-java 5.1.x\", e);\n}","typeGuard":null,"tryCatchPattern":"try { fetcher.open(conn, file, pos, serverId, false); }\ncatch (IOException e) {\n    if (e.getMessage().contains(\"Unable to load com.mysql.jdbc.ConnectionImpl\"))\n        throw new IOException(\"driver 8.x on classpath - pin connector/j 5.1.x or use a cj-compatible build\", e);\n    throw e;\n}","preventionTips":["Depend on mysql-connector-java 5.1.x in your pom for this dbsync fork.","Run a startup Class.forName probe to catch the missing class early.","Avoid mixing driver 8.x onto the classpath."],"tags":["binlog","classpath","driver-compat","mysql","classloading"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}