{"record":{"id":"9e79be1c6a82e846","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-store-item-in-database","errorCode":null,"errorMessage":"Failed to store item in database","messagePattern":"Failed to store item in 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":384,"sourceCode":"    }\n\n    @Override\n    public void putItem(StoreItem item) {\n        validatePutItem(item);\n\n        lock.writeLock().lock();\n        try {\n            String itemId = createItemId(item.getNamespace(), item.getKey());\n            String itemHash = createItemHash(itemId);\n            String namespaceJson = objectMapper.writeValueAsString(item.getNamespace());\n            String valueJson = objectMapper.writeValueAsString(item.getValue());\n\n            try (Connection conn = dataSource.getConnection()) {\n                executeUpsert(conn, itemId, itemHash, namespaceJson, item.getKey(), valueJson,\n                        new Timestamp(item.getCreatedAt()), new Timestamp(item.getUpdatedAt()));\n            }\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to store item in database\", e);\n        } finally {\n            lock.writeLock().unlock();\n        }\n    }\n\n    /**\n     * Execute UPSERT using dialect-specific SQL for mainstream databases. Falls back to\n     * a generic UPDATE-then-INSERT path for unsupported dialects.\n     *\n     * @param conn          database connection\n     * @param itemId        item id\n     * @param namespaceJson serialized namespace\n     * @param key           key name\n     * @param valueJson     serialized value\n     * @param createdAt     created timestamp\n     * @param updatedAt     updated timestamp\n     * @throws SQLException if SQL execution fails\n     */","sourceCodeStart":366,"sourceCodeEnd":402,"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#L366-L402","documentation":"putItem wraps all database work (connection acquisition, upsert execution) in a try block and rethrows any failure as RuntimeException(\"Failed to store item in database\", e). The original cause (SQL error, connection failure, constraint violation) is attached as the cause.","triggerScenarios":"Any exception inside putItem: the DB is unreachable, the store table does not exist, a column size is exceeded, a unique/PK constraint fails, or a lock/interrupt occurs while holding the write lock.","commonSituations":"Database down or wrong credentials at runtime; migration not run so the store table is missing; value JSON exceeding column length; network interruption mid-write.","solutions":["Inspect the wrapped cause via e.getCause() to find the real SQL error","Verify connectivity (host/port/credentials) and that the store table exists (run schema initialization/migrations)","Check the value size against column limits and retry with valid data"],"exampleFix":"// before\nstore.putItem(item); // opaque RuntimeException\n// after\ntry {\n    store.putItem(item);\n} catch (RuntimeException e) {\n    log.error(\"store put failed\", e.getCause());\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"try (Connection c = dataSource.getConnection()) { /* connectivity check before writes */ }","typeGuard":null,"tryCatchPattern":"try { store.putItem(item); } catch (RuntimeException e) { Throwable cause = e.getCause(); log.error(\"putItem failed: {}\", cause, cause); if (cause instanceof java.sql.SQLTransientException) { /* retry */ } }","preventionTips":["Run schema initialization/migrations before using the store","Monitor DB connectivity and pool health","Keep values within column size limits; validate JSON payload size","Always log e.getCause(), not just the wrapper message"],"tags":["database","jdbc","write-failure"],"backgroundTag":"database-write-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"}