{"record":{"id":"5092742eb4223ae6","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-insert-checkpoint-509274","errorCode":null,"errorMessage":"Unable to insert checkpoint","messagePattern":"Unable to insert 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":474,"sourceCode":"\n\t\t\t\tString encodedState = encodeState(checkpoint.getState());\n\t\t\t\tinsertCheckpointStatement.setString(1, checkpoint.getId());\n\t\t\t\tinsertCheckpointStatement.setString(2, checkpoint.getNodeId());\n\t\t\t\tinsertCheckpointStatement.setString(3, checkpoint.getNextNodeId());\n\t\t\t\tinsertCheckpointStatement.setObject(4, encodedState, OracleType.JSON);\n\t\t\t\tinsertCheckpointStatement.setString(5, stateSerializer.contentType());\n\t\t\t\tinsertCheckpointStatement.setString(6, threadName);\n\n\t\t\t\tinsertCheckpointStatement.execute();\n\t\t\t}\n\n\t\t\tconn.commit();\n\t\t\tlog.debug(\"Checkpoint {} for thread {} inserted successfully.\", checkpoint.getId(), threadName);\n\t\t}\n\t\tcatch (SQLException | IOException ex) {\n\t\t\tlog.error(\"Error inserting checkpoint with id {} in thread {}\", checkpoint.getId(), threadName, ex);\n\t\t\trollback(conn, checkpoint, threadName);\n\t\t\tthrow new Exception(\"Unable to insert checkpoint\", ex);\n\t\t}\n\t}\n\n\t@Override\n\tprotected void updateCheckpoint(String threadName, String checkpointId, Checkpoint checkpoint) throws Exception {\n\t\tConnection conn = null;\n\n\t\ttry (Connection ignored = conn = dataSource.getConnection()) {\n\t\t\tconn.setAutoCommit(false);\n\n\t\t\ttry (PreparedStatement preparedStatement = conn.prepareStatement(UPDATE_CHECKPOINT)) {\n\t\t\t\tString encodedState = encodeState(checkpoint.getState());\n\t\t\t\tpreparedStatement.setString(1, checkpoint.getId());\n\t\t\t\tpreparedStatement.setString(2, checkpoint.getNodeId());\n\t\t\t\tpreparedStatement.setString(3, checkpoint.getNextNodeId());\n\t\t\t\tpreparedStatement.setObject(4, encodedState, OracleType.JSON);\n\t\t\t\tpreparedStatement.setString(5, stateSerializer.contentType());\n\t\t\t\tpreparedStatement.setString(6, checkpointId);","sourceCodeStart":456,"sourceCodeEnd":492,"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#L456-L492","documentation":"insertCheckpoint writes a new checkpoint row inside a transaction. On SQLException or IOException the transaction is rolled back (after logging) and a generic Exception with 'Unable to insert checkpoint' is thrown. The original failure (SQL problem, serialization failure) is preserved as the cause.","triggerScenarios":"Saving a checkpoint during graph execution when the INSERT fails: constraint violation, table missing, connection lost, statement timeout, or the checkpoint state cannot be serialized (IOException).","commonSituations":"Table not created (init step skipped); unique key collisions on (thread, checkpointId); Oracle connection pool exhausted or network drop; state containing non-serializable objects with a Java serializer.","solutions":["Inspect the cause and the logged 'Error inserting checkpoint' entry for the exact SQL/IO failure","Run the saver's DB initialization (create-table) step or create the checkpoint table manually","Check for duplicate checkpoint ids / constraint violations on the target table","Verify connection health (pool limits, network) and that the state is serializable by the configured stateSerializer"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// pre-check table exists and is writable\ntry (Connection c = dataSource.getConnection()) {\n    DatabaseMetaData md = c.getMetaData();\n    try (ResultSet rs = md.getTables(null, null, \"CKP_CHECKPOINTS\", null)) {\n        if (!rs.next()) throw new IllegalStateException(\"Checkpoint table missing; run DB init\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    // save checkpoint\n} catch (Exception e) {\n    if (isTransient(e.getCause())) { /* retry with backoff */ }\n    else {\n        log.error(\"Checkpoint insert failed permanently: {}\", e.getCause(), e);\n        // fail the run or degrade to in-memory state\n    }\n}","preventionTips":["Run database initialization before first checkpoint save","Size connection pools and statement timeouts for checkpoint write frequency","Ensure state objects are serializable by the configured serializer","Monitor Oracle for constraint violations and table space"],"tags":["oracle","checkpoint","database","insert","transaction-rollback"],"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"}