alibaba/spring-ai-alibaba · error · Exception

Unable to load checkpoint

Error message

Unable to load checkpoint

What it means

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.

Source

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

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

			defineCheckpointColumns(preparedStatement);
			preparedStatement.setString(1, threadName);
			preparedStatement.setString(2, checkpointId);
			try (ResultSet resultSet = preparedStatement.executeQuery()) {
				if (resultSet.next()) {
					return Optional.of(readCheckpoint(resultSet, objectMapper));
				}
				return Optional.empty();
			}
		}
		catch (SQLException | IOException | ClassNotFoundException ex) {
			throw new Exception("Unable to load checkpoint", ex);
		}
	}

	@Override
	protected void insertCheckpoint(String threadName, Checkpoint checkpoint) throws Exception {
		Connection conn = null;

		try (Connection ignored = conn = dataSource.getConnection()) {
			conn.setAutoCommit(false);

			try (PreparedStatement upsertStatement = conn.prepareStatement(UPSERT_THREAD);
				 PreparedStatement insertCheckpointStatement = conn.prepareStatement(INSERT_CHECKPOINT)) {

				upsertStatement.setString(1, UUID.randomUUID().toString());
				upsertStatement.setString(2, threadName);
				upsertStatement.execute();

				String encodedState = encodeState(checkpoint.getState());

View on GitHub (pinned to f82da0b50f)

Solutions

1. Read the wrapped cause to find the underlying SQLException/IOException/ClassNotFoundException
2. Verify the checkpoint id is being looked up in the intended table/schema
3. Fix deserialization issues by restoring the state classes on the classpath or cleaning incompatible rows
4. Check Oracle connectivity and SELECT privileges for the configured user

// check existence first so 'not present' is distinguishable from 'failed to load'
Optional<Checkpoint> cp = Optional.empty();
try {
    cp = saver.getTuple(threadName, checkpointId);
} catch (Exception e) {
    throw new IllegalStateException("Checkpoint lookup failed (infra problem)", e);
}
if (cp.isEmpty()) { /* treat as genuinely missing, not an error */ }

try {
    // load checkpoint by id
} catch (Exception e) {
    log.error("Loading checkpoint {} failed: {}", checkpointId, e.getCause(), e);
    // fallback: use latest checkpoint or recompute
}

When it happens

Trigger: 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).

Common situations: Refactoring state classes so stored snapshots no longer deserialize; database access problems; checkpoint table partially migrated.

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

• Unable to load checkpoints
• Unable to load checkpoints
• Content Type used for store state '%s' is different from one
• Unable to load latest checkpoint
• Unable to insert checkpoint

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