{"record":{"id":"ee4eab8654b02361","repo":"alibaba/spring-ai-alibaba","slug":"unable-to-load-checkpoint-ee4eab","errorCode":null,"errorMessage":"Unable to load checkpoint","messagePattern":"Unable to load 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":439,"sourceCode":"\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}\n\t\t}\n\t\tcatch (SQLException | IOException | ClassNotFoundException ex) {\n\t\t\tthrow new Exception(\"Unable to load checkpoint\", ex);\n\t\t}\n\t}\n\n\t@Override\n\tprotected void insertCheckpoint(String threadName, 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 upsertStatement = conn.prepareStatement(UPSERT_THREAD);\n\t\t\t\t PreparedStatement insertCheckpointStatement = conn.prepareStatement(INSERT_CHECKPOINT)) {\n\n\t\t\t\tupsertStatement.setString(1, UUID.randomUUID().toString());\n\t\t\t\tupsertStatement.setString(2, threadName);\n\t\t\t\tupsertStatement.execute();\n\n\t\t\t\tString encodedState = encodeState(checkpoint.getState());","sourceCodeStart":421,"sourceCodeEnd":457,"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#L421-L457","documentation":"selectCheckpointById loads a single checkpoint by thread name and checkpoint id. If the SELECT or row deserialization throws SQLException, IOException, or ClassNotFoundException, it is wrapped as an Exception with message 'Unable to load checkpoint'. Absence of a row returns Optional.empty() rather than throwing.","triggerScenarios":"Requesting a specific checkpoint by id (history inspection or rollback) when the query fails (connectivity, permissions, bad table) or the row's payload cannot be deserialized (missing class, corrupt data).","commonSituations":"Refactoring state classes so stored snapshots no longer deserialize; database access problems; checkpoint table partially migrated.","solutions":["Read the wrapped cause to find the underlying SQLException/IOException/ClassNotFoundException","Verify the checkpoint id is being looked up in the intended table/schema","Fix deserialization issues by restoring the state classes on the classpath or cleaning incompatible rows","Check Oracle connectivity and SELECT privileges for the configured user"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// check existence first so 'not present' is distinguishable from 'failed to load'\nOptional<Checkpoint> cp = Optional.empty();\ntry {\n    cp = saver.getTuple(threadName, checkpointId);\n} catch (Exception e) {\n    throw new IllegalStateException(\"Checkpoint lookup failed (infra problem)\", e);\n}\nif (cp.isEmpty()) { /* treat as genuinely missing, not an error */ }","typeGuard":null,"tryCatchPattern":"try {\n    // load checkpoint by id\n} catch (Exception e) {\n    log.error(\"Loading checkpoint {} failed: {}\", checkpointId, e.getCause(), e);\n    // fallback: use latest checkpoint or recompute\n}","preventionTips":["Keep referenced state classes on the classpath for the lifetime of stored checkpoints","Verify checkpoint ids against the correct thread before lookups","Watch for corrupt rows after failed writes and clean them","Maintain DB connectivity/permission checks in health probes"],"tags":["oracle","checkpoint","database","deserialization"],"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-14T00:17:10.932Z"}