{"record":{"id":"b60b15dbc70dead9","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-load-latest-checkpoint-b60b15","errorCode":null,"errorMessage":"Unable to load latest checkpoint","messagePattern":"Unable to load latest checkpoint","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":454,"sourceCode":"\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) {\n\t\t\tthrow new Exception(\"Unable to load latest checkpoint\", ex);\n\t\t}\n\t}\n\n\t@Override\n\tprotected Optional<Checkpoint> selectCheckpointById(String threadName, String checkpointId) throws Exception {\n\t\ttry (Connection connection = dataSource.getConnection();\n\t\t\t\tPreparedStatement preparedStatement = connection.prepareStatement(SELECT_CHECKPOINT_BY_ID)) {\n\n\t\t\tpreparedStatement.setString(1, threadName);\n\t\t\tpreparedStatement.setString(2, checkpointId);\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":436,"sourceCodeEnd":472,"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#L436-L472","documentation":"MysqlSaver.selectLatestCheckpoint() wraps SQLException, IOException, or ClassNotFoundException from querying/deserializing the most recent checkpoint of a thread into an Exception with this message. It is thrown when resuming a graph and the latest checkpoint row cannot be read or decoded. An empty result is NOT an error — Optional.empty() is returned.","triggerScenarios":"Resuming a thread (e.g. via stateGraph compiled runnable resume from a checkpointer) when the SELECT of the latest checkpoint fails at the JDBC level, the blob is corrupt, or a serialized class is absent from the classpath.","commonSituations":"MySQL outage or failover mid-run; checkpoint written by a different version of the library with an incompatible serialization format; custom state classes removed after a refactor; shared checkpoint DB across environments.","solutions":["Check the root cause (ex.getCause()) to identify whether it is connectivity, corruption, or a missing class.","Confirm DB connectivity and that the checkpoints table schema matches the current library version.","Align serializer/class versions: redeploy the app with the classes that wrote the checkpoint, or migrate the data.","Clear the corrupted checkpoint rows so the run can start fresh."],"exampleFix":"// before\nRunnable runnable = graph.compile(checkpointSaver);\nrunnable.invoke(inputs, config); // fails with 'Unable to load latest checkpoint'\n// after\ntry {\n    runnable.invoke(inputs, config);\n} catch (Exception e) {\n    if (e.getCause() instanceof ClassNotFoundException cnfe) {\n        log.error(\"State class missing: {}\", cnfe.getMessage());\n    }\n    // start fresh run without resume\n}","handlingStrategy":"fallback","validationCode":"boolean dbUp;\ntry (Connection c = dataSource.getConnection()) { dbUp = c.isValid(2); }","typeGuard":null,"tryCatchPattern":"try {\n    runnable.invoke(inputs, resumeConfig);\n} catch (Exception e) {\n    log.warn(\"resume failed ({}), starting fresh\", e.getCause().toString());\n    runnable.invoke(inputs, freshConfig);\n}","preventionTips":["Fall back to a fresh run when resume fails instead of crashing the workflow.","Share one library version across all services writing to the same checkpoint DB.","Monitor DB connectivity and failover events."],"tags":["mysql","checkpoint","resume","deserialization"],"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-14T05:17:10.506Z"}