{"record":{"id":"8d5981c0db7f616f","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-load-checkpoints","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/h2/H2Saver.java","lineNumber":320,"sourceCode":"\t\t\t\t.nextNodeId(resultSet.getString(3))\n\t\t\t\t.state(decodeState(resultSet.getString(4), resultSet.getString(5)))\n\t\t\t\t.build();\n\t}\n\n\t@Override\n\tprotected LinkedList<Checkpoint> selectCheckpoints(String threadId) throws Exception {\n\t\tLinkedList<Checkpoint> checkpoints = new LinkedList<>();\n\t\ttry (Connection conn = getConnection();\n\t\t\t\tPreparedStatement ps = conn.prepareStatement(SELECT_CHECKPOINTS)) {\n\t\t\tps.setString(1, threadId);\n\t\t\ttry (ResultSet rs = ps.executeQuery()) {\n\t\t\t\twhile (rs.next()) {\n\t\t\t\t\tcheckpoints.add(readCheckpoint(rs));\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 threadId) throws Exception {\n\t\ttry (Connection conn = getConnection();\n\t\t\t\tPreparedStatement ps = conn.prepareStatement(SELECT_LATEST_CHECKPOINT)) {\n\t\t\tps.setString(1, threadId);\n\t\t\ttry (ResultSet rs = ps.executeQuery()) {\n\t\t\t\tif (rs.next()) {\n\t\t\t\t\treturn Optional.of(readCheckpoint(rs));\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);","sourceCodeStart":302,"sourceCodeEnd":338,"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/h2/H2Saver.java#L302-L338","documentation":"H2Saver.selectCheckpoints reads all checkpoints for a thread from the H2 database. Any SQLException (or deserialization IOException/ClassNotFoundException from readCheckpoint) is wrapped in a checked Exception with message 'Unable to load checkpoints', preserving the cause.","triggerScenarios":"Calling the saver's load/list checkpoint path when the H2 table is missing, the DB file is locked/corrupt, connection fails, or stored rows cannot be deserialized.","commonSituations":"H2 database file deleted or corrupted, schema mismatch after upgrade, concurrent access to the same H2 file from two processes, classpath changes breaking deserialization of stored classes.","solutions":["Inspect the cause chain (getCause()) for the underlying SQLException/IOException","Verify the H2 database file exists, is not locked by another process, and the table schema matches","Restore from backup or start with a fresh checkpoint database if corrupt","Ensure the same serializer and classpath versions used for writing are present when reading"],"exampleFix":"// before\ntry { saver.release(conn); } catch (Exception e) {}\n// after\ntry { saver.release(conn); } catch (Exception e) {\n    log.error(\"checkpoint load failed\", e.getCause());\n    throw new UncheckedIOException(new IOException(e.getCause()));\n}","handlingStrategy":"try-catch","validationCode":"try (Connection c = getConnection(); ResultSet rs = c.createStatement().executeQuery(\"SELECT 1 FROM checkpoints LIMIT 1\")) { /* table reachable */ }","typeGuard":null,"tryCatchPattern":"try { checkpoints = saver.getAll(threadId); } catch (Exception e) { Throwable root = e.getCause(); log.error(\"H2 read failed\", root); }","preventionTips":["Monitor H2 file locks and DB health","Pin library versions to keep stored classes deserializable","Back up checkpoint databases","Verify schema after upgrades"],"tags":["h2","database","checkpoint","jdbc"],"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"}