{"record":{"id":"930247f6834d74b6","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-load-latest-checkpoint-930247","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/oracle/OracleSaver.java","lineNumber":418,"sourceCode":"\t}\n\n\t@Override\n\tprotected Optional<Checkpoint> selectLatestCheckpoint(String threadName) throws Exception {\n\t\tObjectMapper objectMapper = osonObjectMapper();\n\t\ttry (Connection connection = dataSource.getConnection();\n\t\t\t\tPreparedStatement preparedStatement = connection.prepareStatement(SELECT_LATEST_CHECKPOINT)) {\n\n\t\t\tdefineCheckpointColumns(preparedStatement);\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, objectMapper));\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\tObjectMapper objectMapper = osonObjectMapper();\n\t\ttry (Connection connection = dataSource.getConnection();\n\t\t\t\tPreparedStatement preparedStatement = connection.prepareStatement(SELECT_CHECKPOINT_BY_ID)) {\n\n\t\t\tdefineCheckpointColumns(preparedStatement);\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, objectMapper));\n\t\t\t\t}\n\t\t\t\treturn Optional.empty();\n\t\t\t}","sourceCodeStart":400,"sourceCodeEnd":436,"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/oracle/OracleSaver.java#L400-L436","documentation":"selectLatestCheckpoint queries Oracle for the most recent checkpoint of a thread and deserializes it with readCheckpoint. Any SQLException, IOException, or ClassNotFoundException during that work is wrapped in an Exception with message 'Unable to load latest checkpoint'. An empty result set is not an error; only query/deserialization failures are thrown.","triggerScenarios":"Resuming a graph/thread state (e.g. via checkpoint loading on session resume) when the latest-checkpoint SELECT fails due to connectivity, missing table, or the stored row cannot be decoded (unknown class, corrupt payload).","commonSituations":"Database outage or failover during agent run; table schema drift after upgrade; state classes renamed so ClassNotFoundException occurs while reading; bad credentials.","solutions":["Check the wrapped cause to distinguish SQL failure vs deserialization failure","Verify table existence, connectivity, and credentials; test the SELECT manually","Clean or migrate unreadable rows (e.g. after class/package renames) so the latest checkpoint can deserialize","Rebuild thread state by re-running the workflow if the latest checkpoint is unrecoverable"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// verify connectivity and that the thread has at least one checkpoint before resuming\ntry (Connection c = dataSource.getConnection();\n     PreparedStatement ps = c.prepareStatement(\"SELECT COUNT(*) FROM CKP_CHECKPOINTS WHERE THREAD_NAME = ?\")) {\n    ps.setString(1, threadName);\n    try (ResultSet rs = ps.executeQuery()) { rs.next(); return rs.getInt(1) > 0; }\n} catch (SQLException e) { throw new IllegalStateException(\"DB not ready\", e); }","typeGuard":null,"tryCatchPattern":"try {\n    // resume using latest checkpoint\n} catch (Exception e) {\n    log.error(\"Could not load latest checkpoint: {}\", e.getCause(), e);\n    // fallback: start the thread from scratch if resume is not critical\n}","preventionTips":["Log and alert on e.getCause() to distinguish SQL vs deserialization failures","Avoid renaming/moving state classes; migrate stored checkpoints if you must","Test DB failover behavior for long-running agent sessions","Validate schema compatibility after each upgrade of the framework"],"tags":["oracle","checkpoint","database","sql","resume"],"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"}