{"record":{"id":"284a4907c0648ecc","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-load-checkpoints-284a49","errorCode":null,"errorMessage":"Unable to load checkpoints","messagePattern":"Unable to load checkpoints","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/mysql/MysqlSaver.java","lineNumber":435,"sourceCode":"\n\t/**\n\t * Loads full checkpoint history on demand without retaining it in cache.\n\t */\n\t@Override\n\tprotected LinkedList<Checkpoint> selectCheckpoints(String threadName) throws Exception {\n\t\tLinkedList<Checkpoint> checkpoints = new LinkedList<>();\n\t\ttry (Connection connection = dataSource.getConnection();\n\t\t\t\tPreparedStatement preparedStatement = connection.prepareStatement(SELECT_CHECKPOINTS)) {\n\n\t\t\tpreparedStatement.setString(1, threadName);\n\t\t\ttry (ResultSet resultSet = preparedStatement.executeQuery()) {\n\t\t\t\twhile (resultSet.next()) {\n\t\t\t\t\tcheckpoints.add(readCheckpoint(resultSet));\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tcatch (SQLException | IOException | ClassNotFoundException ex) {\n\t\t\tthrow new Exception(\"Unable to load checkpoints\", ex);\n\t\t}\n\t\treturn checkpoints;\n\t}\n\n\t@Override\n\tprotected Optional<Checkpoint> selectLatestCheckpoint(String threadName) throws Exception {\n\t\ttry (Connection connection = dataSource.getConnection();\n\t\t\t\tPreparedStatement preparedStatement = connection.prepareStatement(SELECT_LATEST_CHECKPOINT)) {\n\n\t\t\tpreparedStatement.setString(1, threadName);\n\t\t\ttry (ResultSet resultSet = preparedStatement.executeQuery()) {\n\t\t\t\tif (resultSet.next()) {\n\t\t\t\t\treturn Optional.of(readCheckpoint(resultSet));\n\t\t\t\t}\n\t\t\t\treturn Optional.empty();\n\t\t\t}\n\t\t}\n\t\tcatch (SQLException | IOException | ClassNotFoundException ex) {","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/mysql/MysqlSaver.java#L417-L453","documentation":"MysqlSaver.selectCheckpoints() wraps any SQLException, IOException, or ClassNotFoundException raised while querying and deserializing all checkpoints for a thread into a generic Exception with this message. It means the checkpoint rows for the thread could not be read from MySQL or the stored checkpoint blob could not be deserialized back into a Checkpoint object.","triggerScenarios":"Calling loadState/compiled graph resume for a threadId when: the datasource cannot reach MySQL or the connection/query fails (SQLException); the checkpoint state blob is corrupt or was written by an incompatible serializer (IOException); or a class stored in the checkpoint state is missing on the classpath (ClassNotFoundException, e.g. a custom state class was renamed or removed).","commonSituations":"Database is down or credentials/network changed; checkpoint table schema drifted between library versions; a user state class referenced by a serialized checkpoint was refactored; deserialization across JVM versions or across different application deployments sharing the same database.","solutions":["Inspect the wrapped cause (ex.getCause()) to distinguish SQLException vs IOException vs ClassNotFoundException and fix accordingly.","Verify MySQL connectivity, credentials, and that the checkpoints table exists with the expected schema (re-run any schema migration for the new library version).","Ensure all classes stored in checkpoint state are on the classpath with identical fully-qualified names and compatible serialVersionUID.","If the checkpoint data is unrecoverable, delete the stale rows for the thread and restart the run from scratch."],"exampleFix":"// before\nCheckpoint cp = saver.getCheckpoints(threadId); // throws generic Exception\n// after\ntry {\n    Checkpoint cp = saver.getCheckpoints(threadId);\n} catch (Exception e) {\n    log.error(\"Checkpoint load failed\", e.getCause());\n    // fall back to fresh run or repair DB schema/classpath\n}","handlingStrategy":"try-catch","validationCode":"// verify DB reachable and classes loadable before reading checkpoints\ntry (Connection c = dataSource.getConnection()) { c.isValid(2); }\nClass.forName(\"com.alibaba.cloud.ai.graph.Checkpoint\");","typeGuard":null,"tryCatchPattern":"try {\n    saver.getCheckpoints(threadId);\n} catch (Exception e) {\n    log.error(\"checkpoint load failed\", e.getCause());\n    // fallback: start a fresh run\n}","preventionTips":["Run schema migrations for the checkpoint table on every version upgrade.","Keep serialized state classes Serializable with stable serialVersionUID and stable package names.","Add DB health checks before resuming graph runs."],"tags":["mysql","checkpoint","deserialization","database"],"backgroundTag":"database-query-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}