alibaba/spring-ai-alibaba · error · Exception

Unable to load checkpoints

Error message

Unable to load checkpoints

What it means

selectCheckpoints runs the SQL query that lists all checkpoints for a thread and deserializes each row via readCheckpoint. Any SQLException, IOException, or ClassNotFoundException raised during query execution or row deserialization is wrapped and rethrown as a generic Exception with the message 'Unable to load checkpoints', keeping the saver's checked-exception contract while hiding the root cause in the cause chain.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/oracle/OracleSaver.java:397

	 * Loads full checkpoint history on demand without retaining it in cache.
	 */
	@Override
	protected LinkedList<Checkpoint> selectCheckpoints(String threadName) throws Exception {
		LinkedList<Checkpoint> checkpoints = new LinkedList<>();
		ObjectMapper objectMapper = osonObjectMapper();
		try (Connection connection = dataSource.getConnection();
				PreparedStatement preparedStatement = connection.prepareStatement(SELECT_CHECKPOINTS)) {

			defineCheckpointColumns(preparedStatement);
			preparedStatement.setString(1, threadName);
			try (ResultSet resultSet = preparedStatement.executeQuery()) {
				while (resultSet.next()) {
					checkpoints.add(readCheckpoint(resultSet, objectMapper));
				}
			}
		}
		catch (SQLException | IOException | ClassNotFoundException ex) {
			throw new Exception("Unable to load checkpoints", ex);
		}
		return checkpoints;
	}

	@Override
	protected Optional<Checkpoint> selectLatestCheckpoint(String threadName) throws Exception {
		ObjectMapper objectMapper = osonObjectMapper();
		try (Connection connection = dataSource.getConnection();
				PreparedStatement preparedStatement = connection.prepareStatement(SELECT_LATEST_CHECKPOINT)) {

			defineCheckpointColumns(preparedStatement);
			preparedStatement.setString(1, threadName);
			try (ResultSet resultSet = preparedStatement.executeQuery()) {
				if (resultSet.next()) {
					return Optional.of(readCheckpoint(resultSet, objectMapper));
				}
				return Optional.empty();
			}

View on GitHub (pinned to f82da0b50f)

Solutions

  1. Inspect the wrapped cause (ex.getCause()) printed by the log to identify the real SQLException/IOException/ClassNotFoundException
  2. Verify the checkpoint table exists and the configured user has SELECT privileges on it
  3. Confirm JDBC connectivity (URL, credentials, driver on classpath) with a simple test query
  4. Recreate or clean corrupted/legacy checkpoint rows that fail deserialization, e.g. rows written by an older serializer or removed state classes
Defensive patterns

Strategy: try-catch

Validate before calling

// health-check before listing checkpoints
try (Connection c = dataSource.getConnection();
     PreparedStatement ps = c.prepareStatement("SELECT 1 FROM CKP_CHECKPOINTS WHERE 1=0")) {
    ps.executeQuery();
} catch (SQLException e) {
    throw new IllegalStateException("Oracle checkpoint table unavailable: " + e.getMessage(), e);
}

Try / catch

try {
    // list/load checkpoints
} catch (Exception e) {
    Throwable cause = e.getCause();
    log.error("Checkpoint load failed: {}", cause == null ? e : cause.getMessage(), cause);
    // fallback: start workflow without restored state, or retry transient SQL errors
}

Prevention

When it happens

Trigger: Calling a list/load-checkpoints API against Oracle when the table is missing or inaccessible, credentials are wrong, the connection fails, or a stored row cannot be deserialized (e.g. class-not-found for state objects, corrupt base64 payload).

Common situations: Checkpoint table dropped or schema migrated; Oracle credentials/network changed; old checkpoints reference classes that no longer exist after a refactor; JDBC driver missing.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/d9b4c117b4b6d9a2. Report an issue: GitHub.