alibaba/spring-ai-alibaba · error · RuntimeException

Failed to retrieve item from database

Error message

Failed to retrieve item from database

What it means

getItem catches any exception raised while querying the item (connection acquisition, SQL execution, result mapping) and rethrows it as RuntimeException("Failed to retrieve item from database", e), releasing the read lock in finally. The real cause is preserved as the cause.

Solutions

1. Read e.getCause() to identify the underlying SQL/IO error
2. Verify the store table exists and the DB user has SELECT permission
3. Check that stored value JSON still matches the deserializer; clear or migrate stale rows after version upgrades

Example fix

// before
Optional<StoreItem> item = store.getItem(ns, key); // opaque failure
// after
try {
    item = store.getItem(ns, key);
} catch (RuntimeException e) {
    log.warn("getItem failed: {}", e.getCause() == null ? e : e.getCause().getMessage());
    return Optional.empty();
}

try (Connection c = dataSource.getConnection(); PreparedStatement ps = c.prepareStatement("SELECT 1")) { ps.execute(); }

try { Optional<StoreItem> item = store.getItem(ns, key); } catch (RuntimeException e) { log.warn("getItem failed: {}", e.getCause()); return Optional.empty(); /* or rethrow for fail-fast */ }

When it happens

Trigger: Calling getItem when the DB is unreachable, the table/schema is missing, the SQL query fails (bad column, permissions), or resultSetToStoreItem cannot deserialize the stored JSON value.

Common situations: Expired connection pool after DB restart; schema drift after an upgrade changing JSON shape or columns; insufficient SELECT grants for the configured user.

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

• Failed to clear database store
• Failed to delete item from database
• Failed to get store size from database
• Failed to retrieve all items from database
• Failed to store item in database

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

Appendix: source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/DatabaseStore.java:601

        try {
            String itemId = createItemId(namespace, key);
            String itemHash = createItemHash(itemId);
            String sql = "SELECT namespace, key_name, value_json, created_at, updated_at FROM " + tableName
                    + " WHERE id_hash = ?";

            try (Connection conn = dataSource.getConnection(); PreparedStatement stmt = conn.prepareStatement(sql)) {

                stmt.setString(1, itemHash);
                ResultSet rs = stmt.executeQuery();

                if (rs.next()) {
                    return Optional.of(resultSetToStoreItem(rs));
                }

                return Optional.empty();
            }
        } catch (Exception e) {
            throw new RuntimeException("Failed to retrieve item from database", e);
        } finally {
            lock.readLock().unlock();
        }
    }

    @Override
    public boolean deleteItem(List<String> namespace, String key) {
        validateDeleteItem(namespace, key);

        lock.writeLock().lock();
        try {
            String itemId = createItemId(namespace, key);
            String itemHash = createItemHash(itemId);
            String sql = "DELETE FROM " + tableName + " WHERE id_hash = ?";

            try (Connection conn = dataSource.getConnection(); PreparedStatement stmt = conn.prepareStatement(sql)) {

                stmt.setString(1, itemHash);

View on GitHub (pinned to f82da0b50f)