{"record":{"id":"782a15e03ed45107","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-update-checkpoint","errorCode":null,"errorMessage":"Unable to update checkpoint","messagePattern":"Unable to update 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/h2/H2Saver.java","lineNumber":443,"sourceCode":"\t\t\ttry (PreparedStatement ps = conn.prepareStatement(UPDATE_CHECKPOINT)) {\n\t\t\t\tps.setString(1, checkpoint.getId());\n\t\t\t\tps.setString(2, checkpoint.getNodeId());\n\t\t\t\tps.setString(3, checkpoint.getNextNodeId());\n\t\t\t\tps.setString(4, encodeState(checkpoint.getState()));\n\t\t\t\tps.setString(5, stateSerializer.contentType());\n\t\t\t\tps.setString(6, checkpointId);\n\t\t\t\tps.setString(7, threadId);\n\t\t\t\tint rowsAffected = ps.executeUpdate();\n\t\t\t\tif (rowsAffected == 0) {\n\t\t\t\t\tconn.rollback();\n\t\t\t\t\tthrow new NoSuchElementException(format(\"Checkpoint with id %s not found!\", checkpointId));\n\t\t\t\t}\n\t\t\t}\n\t\t\tconn.commit();\n\t\t}\n\t\tcatch (SQLException | IOException ex) {\n\t\t\trollback(conn, threadId);\n\t\t\tthrow new Exception(\"Unable to update checkpoint\", ex);\n\t\t}\n\t}\n\n\t@Override\n\tprotected void deleteCheckpoints(String threadId, Collection<String> checkpointIds) throws Exception {\n\t\tif (checkpointIds.isEmpty()) {\n\t\t\treturn;\n\t\t}\n\t\tString placeholders = String.join(\", \", Collections.nCopies(checkpointIds.size(), \"?\"));\n\t\ttry (Connection conn = getConnection();\n\t\t\t\tPreparedStatement ps = conn.prepareStatement(DELETE_CHECKPOINTS.formatted(placeholders))) {\n\t\t\tint index = 1;\n\t\t\tfor (String checkpointId : checkpointIds) {\n\t\t\t\tps.setString(index++, checkpointId);\n\t\t\t}\n\t\t\tps.setString(index, threadId);\n\t\t\tps.executeUpdate();\n\t\t}","sourceCodeStart":425,"sourceCodeEnd":461,"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#L425-L461","documentation":"updateCheckpoint wraps SQLException or IOException occurring during the UPDATE transaction (prepare, execute, serialize state, commit) into Exception 'Unable to update checkpoint'. The transaction is rolled back first, so the stored checkpoint remains unchanged.","triggerScenarios":"Updating an existing checkpoint when: the H2 connection drops mid-transaction, the checkpoints table is missing/corrupt, checkpoint state cannot be serialized by stateSerializer (IOException), or commit fails due to lock conflicts.","commonSituations":"Concurrent writers locking the same checkpoint row; database file locked or disk full; serializer mismatch after upgrading the library; schema drift after manual table edits.","solutions":["Inspect getCause() for the underlying SQL or serialization error.","Retry the update — the rollback guarantees consistency, transient lock/connection issues resolve.","Re-create the checkpoints table if the schema drifted from the current saver version.","Verify checkpoint state serializes with the configured stateSerializer."],"exampleFix":"// before: one-shot update, transient lock fails the run\nsaver.update(threadId, id, checkpoint);\n// after: retry transient failures\nfor (int i = 0; i < 3; i++) {\n  try { saver.update(threadId, id, checkpoint); break; }\n  catch (Exception e) { if (i == 2) throw e; sleep(100L * (i + 1)); }\n}","handlingStrategy":"retry","validationCode":"// ensure state serializes before touching the DB\nserializer.write(checkpoint.getState(), new ByteArrayOutputStream());","typeGuard":null,"tryCatchPattern":"try { saver.update(threadId, id, checkpoint); }\ncatch (Exception e) { if (isTransient(e.getCause())) retryWithBackoff(3); else throw new RuntimeException(\"checkpoint update failed\", e.getCause()); }","preventionTips":["Retry transient SQL failures — the method rolls back safely","Keep table schema in sync with library version","Limit concurrent writers per checkpoint row"],"tags":["database","h2","transaction","update"],"backgroundTag":"database-write-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"}