{"record":{"id":"08b9ac7da082af6e","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-load-checkpoint-08b9ac","errorCode":null,"errorMessage":"Unable to load checkpoint","messagePattern":"Unable to load 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":473,"sourceCode":"\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) {\n\t\t\tthrow new Exception(\"Unable to load checkpoint\", ex);\n\t\t}\n\t}\n\n\t@Override\n\tprotected void insertCheckpoint(String threadName, Checkpoint checkpoint) throws Exception {\n\t\tConnection conn = null;\n\t\ttry (Connection ignored = conn = dataSource.getConnection()) {\n\t\t\tconn.setAutoCommit(false);\n\n\t\t\ttry (PreparedStatement upsertStatement = conn.prepareStatement(UPSERT_THREAD);\n\t\t\t\t\tPreparedStatement insertCheckpointStatement = conn.prepareStatement(INSERT_CHECKPOINT)) {\n\n\t\t\t\tupsertStatement.setString(1, UUID.randomUUID().toString());\n\t\t\t\tupsertStatement.setString(2, threadName);\n\t\t\t\tupsertStatement.execute();\n\n\t\t\t\tinsertCheckpointStatement.setString(1, checkpoint.getId());\n\t\t\t\tinsertCheckpointStatement.setString(2, checkpoint.getNodeId());","sourceCodeStart":455,"sourceCodeEnd":491,"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#L455-L491","documentation":"MysqlSaver.selectCheckpointById() wraps SQLException, IOException, or ClassNotFoundException from fetching and deserializing one checkpoint by (threadName, checkpointId) into an Exception with this message. A missing row returns Optional.empty() rather than throwing; the exception always indicates a read/decode failure.","triggerScenarios":"Looking up a specific checkpoint (e.g. time-travel/replay to a checkpointId) when the SELECT fails, the serialized state blob is unreadable, or a class in the checkpoint state cannot be loaded.","commonSituations":"Passing a checkpointId whose row's blob was written by another app version; DB connectivity problems; custom state class renamed; schema migrations altering column types.","solutions":["Inspect ex.getCause() to determine the failing layer (SQL vs IO vs class loading).","Verify connectivity and schema of the checkpoint table.","Restore classpath compatibility for serialized state classes (same FQCN and serialVersionUID).","If the blob is corrupt, delete that checkpoint row and replay from an earlier checkpoint."],"exampleFix":"// before\nOptional<Checkpoint> cp = saver.getCheckpoint(threadId, checkpointId);\n// after\ntry {\n    Optional<Checkpoint> cp = saver.getCheckpoint(threadId, checkpointId);\n} catch (Exception e) {\n    log.error(\"Failed loading checkpoint {}\", checkpointId, e.getCause());\n    // fall back to latest checkpoint or fresh run\n}","handlingStrategy":"try-catch","validationCode":"// confirm checkpoint id exists before deep-loading it\nboolean exists = !saver.getCheckpoints(threadId).isEmpty();","typeGuard":null,"tryCatchPattern":"try {\n    Optional<Checkpoint> cp = saver.getCheckpoint(threadId, checkpointId);\n} catch (Exception e) {\n    log.error(\"cannot decode checkpoint {}\", checkpointId, e.getCause());\n}","preventionTips":["Verify checkpoint ids against the current thread before replay/time-travel.","Avoid refactoring serialized state classes without a data migration.","Keep checkpoint table schema in sync with the library version."],"tags":["mysql","checkpoint","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"}