alibaba/spring-ai-alibaba · error · RuntimeException

Failed to store item in database

Error message

Failed to store item in database

What it means

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.

Solutions

1. Inspect the wrapped cause via e.getCause() to find the real SQL error
2. Verify connectivity (host/port/credentials) and that the store table exists (run schema initialization/migrations)
3. Check the value size against column limits and retry with valid data

Example fix

// before
store.putItem(item); // opaque RuntimeException
// after
try {
    store.putItem(item);
} catch (RuntimeException e) {
    log.error("store put failed", e.getCause());
    throw e;
}

try (Connection c = dataSource.getConnection()) { /* connectivity check before writes */ }

try { store.putItem(item); } catch (RuntimeException e) { Throwable cause = e.getCause(); log.error("putItem failed: {}", cause, cause); if (cause instanceof java.sql.SQLTransientException) { /* retry */ } }

When it happens

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

Common situations: 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.

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 retrieve item from database

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/9e79be1c6a82e846. 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:384

    }

    @Override
    public void putItem(StoreItem item) {
        validatePutItem(item);

        lock.writeLock().lock();
        try {
            String itemId = createItemId(item.getNamespace(), item.getKey());
            String itemHash = createItemHash(itemId);
            String namespaceJson = objectMapper.writeValueAsString(item.getNamespace());
            String valueJson = objectMapper.writeValueAsString(item.getValue());

            try (Connection conn = dataSource.getConnection()) {
                executeUpsert(conn, itemId, itemHash, namespaceJson, item.getKey(), valueJson,
                        new Timestamp(item.getCreatedAt()), new Timestamp(item.getUpdatedAt()));
            }
        } catch (Exception e) {
            throw new RuntimeException("Failed to store item in database", e);
        } finally {
            lock.writeLock().unlock();
        }
    }

    /**
     * Execute UPSERT using dialect-specific SQL for mainstream databases. Falls back to
     * a generic UPDATE-then-INSERT path for unsupported dialects.
     *
     * @param conn          database connection
     * @param itemId        item id
     * @param namespaceJson serialized namespace
     * @param key           key name
     * @param valueJson     serialized value
     * @param createdAt     created timestamp
     * @param updatedAt     updated timestamp
     * @throws SQLException if SQL execution fails
     */

View on GitHub (pinned to f82da0b50f)