{"record":{"id":"01fe45b082b8cbcd","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-delete-retained-checkpoints-01fe45","errorCode":null,"errorMessage":"Unable to delete retained checkpoints","messagePattern":"Unable to delete retained 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/mysql/MysqlSaver.java","lineNumber":554,"sourceCode":"\t}\n\n\t@Override\n\tprotected void deleteCheckpoints(String threadName, Collection<String> checkpointIds) throws Exception {\n\t\tif (checkpointIds.isEmpty()) {\n\t\t\treturn;\n\t\t}\n\t\ttry (Connection connection = dataSource.getConnection();\n\t\t\t\tPreparedStatement preparedStatement = connection.prepareStatement(\n\t\t\t\t\t\tDELETE_CHECKPOINTS.formatted(String.join(\", \", Collections.nCopies(checkpointIds.size(), \"?\"))))) {\n\t\t\tpreparedStatement.setString(1, threadName);\n\t\t\tint index = 2;\n\t\t\tfor (String checkpointId : checkpointIds) {\n\t\t\t\tpreparedStatement.setString(index++, checkpointId);\n\t\t\t}\n\t\t\tpreparedStatement.executeUpdate();\n\t\t}\n\t\tcatch (SQLException ex) {\n\t\t\tthrow new Exception(\"Unable to delete retained checkpoints\", ex);\n\t\t}\n\t}\n\n\t@Override\n\tprotected void releaseThread(String threadName) 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 preparedStatement = conn.prepareStatement(RELEASE_THREAD)) {\n\t\t\t\tpreparedStatement.setString(1, threadName);\n\t\t\t\tint rowsAffected = preparedStatement.executeUpdate();\n\t\t\t\tif (rowsAffected == 0) {\n\t\t\t\t\tconn.rollback();\n\t\t\t\t\tthrow new IllegalStateException(format(\"Thread '%s' not found or already released\", threadName));\n\t\t\t\t}\n\t\t\t}\n","sourceCodeStart":536,"sourceCodeEnd":572,"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#L536-L572","documentation":"deleteCheckpoints() removes a set of checkpoint ids for a thread and wraps any SQLException from the batched DELETE into an Exception with this message. Despite the wording ('retained checkpoints'), it fails when deleting the specified checkpoints, typically due to a database-level problem.","triggerScenarios":"Checkpoint history pruning (release/releaseThread with retained ids) when the DELETE fails: connection loss, too many parameters for the IN clause, lock contention, or missing/corrupt table.","commonSituations":"Very large checkpoint lists exceeding DB limits for IN-clause parameters; long-running transactions holding row locks on the checkpoint table; table dropped or renamed after a migration.","solutions":["Check the wrapped SQLException for the exact failure (lock timeout, parameter limit).","Split large checkpointId collections into smaller batches for deletion.","Verify the checkpoints table exists and the DB user has DELETE privileges.","Reduce lock contention by pruning checkpoints outside peak load or in smaller transactions."],"exampleFix":"// before\nsaver.deleteCheckpoints(threadId, thousandsOfIds); // may exceed IN limits\n// after\nfor (List<String> batch : Lists.partition(ids, 500)) {\n    saver.deleteCheckpoints(threadId, batch);\n}","handlingStrategy":"try-catch","validationCode":"if (ids.size() > 1000) throw new IllegalArgumentException(\"batch checkpoint deletions, got \" + ids.size());","typeGuard":null,"tryCatchPattern":"try {\n    saver.deleteCheckpoints(threadId, ids);\n} catch (Exception e) {\n    log.error(\"checkpoint prune failed for {}\", threadId, e.getCause());\n    // non-fatal: schedule retry\n}","preventionTips":["Delete checkpoints in small batches rather than huge IN lists.","Schedule pruning during low-traffic windows.","Grant the DB user DELETE privileges on the checkpoint table."],"tags":["mysql","checkpoint","delete","cleanup"],"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-17T15:17:12.973Z"}