alibaba/spring-ai-alibaba · error · Exception

Unable to load checkpoints

Error message

Unable to load checkpoints

What it means

PostgresSaver.selectCheckpoints wraps SQLException, IOException, and ClassNotFoundException from reading all checkpoints for a thread into Exception('Unable to load checkpoints'). Any failure executing the SELECT or deserializing the checkpoint rows (including readCheckpoint failures like content-type mismatch) surfaces under this message.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/postgresql/PostgresSaver.java:408

				.build();
	}

	@Override
	protected LinkedList<Checkpoint> selectCheckpoints(String threadId) throws Exception {
		LinkedList<Checkpoint> checkpoints = new LinkedList<>();
		try (Connection conn = getConnection();
				PreparedStatement ps = conn.prepareStatement(SELECT_CHECKPOINTS)) {

			log.trace("Executing select checkpoints:\n---\n{}---", SELECT_CHECKPOINTS);
			ps.setString(1, threadId);
			try (ResultSet rs = ps.executeQuery()) {
				while (rs.next()) {
					checkpoints.add(readCheckpoint(rs));
				}
			}
		}
		catch (SQLException | IOException | ClassNotFoundException ex) {
			throw new Exception("Unable to load checkpoints", ex);
		}
		return checkpoints;
	}

	@Override
	protected Optional<Checkpoint> selectLatestCheckpoint(String threadId) throws Exception {
		try (Connection conn = getConnection();
				PreparedStatement ps = conn.prepareStatement(SELECT_LATEST_CHECKPOINT)) {

			log.trace("Executing select latest checkpoint:\n---\n{}---", SELECT_LATEST_CHECKPOINT);
			ps.setString(1, threadId);
			try (ResultSet rs = ps.executeQuery()) {
				if (rs.next()) {
					return Optional.of(readCheckpoint(rs));
				}
				return Optional.empty();
			}
		}

View on GitHub (pinned to f82da0b50f)

Solutions

  1. Inspect the wrapped cause: SQLException -> check DB connectivity/table schema; ClassNotFoundException -> restore the state classes or migrate the data; IOException -> verify payload integrity and serializer.
  2. Confirm the checkpoint tables exist and match the current version's schema (re-run table initialization if supported).
  3. If a class was renamed, keep a compatibility class or remap serialization before reading old checkpoints.
  4. For transient SQL errors, retry with a healthy connection pool (verify HikariCP settings).

Example fix

// before
// state class renamed between versions -> ClassNotFoundException
public class AgentState implements Serializable { ... }
// after
// keep old class name for deserialization compatibility or migrate rows:
@Deprecated
public class AgentStateOld extends AgentState { } // or clear old checkpoint rows
Defensive patterns

Strategy: retry

Validate before calling

// Java: pre-flight check before loading checkpoints
try (Connection c = dataSource.getConnection()) {
    c.prepareStatement("SELECT 1 FROM checkpoints LIMIT 1").execute(); // table exists & reachable
}

Try / catch

try {
    var checkpoints = saver.list(config);
} catch (Exception e) {
    if ("Unable to load checkpoints".equals(e.getMessage()) && e.getCause() instanceof SQLException) {
        // retry with backoff or fall back to starting a fresh thread
    }
}

Prevention

When it happens

Trigger: Listing checkpoints via the saver repository when the connection is broken/timeout, the checkpoints table is missing or schema drifted, or a row's payload cannot be deserialized (wrong serializer, corrupted Base64/bytes, missing class from ClassNotFoundException).

Common situations: Schema mismatch after upgrading the library (column renames); corrupted rows from a partial write; ClassNotFoundException when state classes were renamed/moved between releases; transient network failures to Postgres.

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/61dc1a0d12972bce. Report an issue: GitHub.