{"record":{"id":"f51a2b0078f1d8fc","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-retrieve-item-from-database","errorCode":null,"errorMessage":"Failed to retrieve item from database","messagePattern":"Failed to retrieve item from database","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/DatabaseStore.java","lineNumber":601,"sourceCode":"        try {\n            String itemId = createItemId(namespace, key);\n            String itemHash = createItemHash(itemId);\n            String sql = \"SELECT namespace, key_name, value_json, created_at, updated_at FROM \" + tableName\n                    + \" WHERE id_hash = ?\";\n\n            try (Connection conn = dataSource.getConnection(); PreparedStatement stmt = conn.prepareStatement(sql)) {\n\n                stmt.setString(1, itemHash);\n                ResultSet rs = stmt.executeQuery();\n\n                if (rs.next()) {\n                    return Optional.of(resultSetToStoreItem(rs));\n                }\n\n                return Optional.empty();\n            }\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to retrieve item from database\", e);\n        } finally {\n            lock.readLock().unlock();\n        }\n    }\n\n    @Override\n    public boolean deleteItem(List<String> namespace, String key) {\n        validateDeleteItem(namespace, key);\n\n        lock.writeLock().lock();\n        try {\n            String itemId = createItemId(namespace, key);\n            String itemHash = createItemHash(itemId);\n            String sql = \"DELETE FROM \" + tableName + \" WHERE id_hash = ?\";\n\n            try (Connection conn = dataSource.getConnection(); PreparedStatement stmt = conn.prepareStatement(sql)) {\n\n                stmt.setString(1, itemHash);","sourceCodeStart":583,"sourceCodeEnd":619,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/DatabaseStore.java#L583-L619","documentation":"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.","triggerScenarios":"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.","commonSituations":"Expired connection pool after DB restart; schema drift after an upgrade changing JSON shape or columns; insufficient SELECT grants for the configured user.","solutions":["Read e.getCause() to identify the underlying SQL/IO error","Verify the store table exists and the DB user has SELECT permission","Check that stored value JSON still matches the deserializer; clear or migrate stale rows after version upgrades"],"exampleFix":"// before\nOptional<StoreItem> item = store.getItem(ns, key); // opaque failure\n// after\ntry {\n    item = store.getItem(ns, key);\n} catch (RuntimeException e) {\n    log.warn(\"getItem failed: {}\", e.getCause() == null ? e : e.getCause().getMessage());\n    return Optional.empty();\n}","handlingStrategy":"try-catch","validationCode":"try (Connection c = dataSource.getConnection(); PreparedStatement ps = c.prepareStatement(\"SELECT 1\")) { ps.execute(); }","typeGuard":null,"tryCatchPattern":"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 */ }","preventionTips":["Confirm SELECT grants for the configured user","Re-run schema migrations after version upgrades and check JSON shape compatibility","Handle transient connection errors with a retry/backoff policy","Log e.getCause() to surface the true SQL error"],"tags":["database","jdbc","read-failure"],"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-17T15:17:12.973Z"}