alibaba/spring-ai-alibaba · error · RuntimeException

Failed to create item hash

Error message

Failed to create item hash

What it means

createItemHash() computes the SHA-256 hash of a namespace/key used as the unique id_hash column, and wraps ANY exception (including NoSuchAlgorithmException or serialization problems) in this RuntimeException. itemHash() calls it, so all item lookups/writes that hash keys can fail with this.

Source

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

    /**
     * Create a fixed-length hash for long business identifiers to keep unique indexes
     * stable across different database dialects.
     *
     * @param itemId original business identifier
     * @return sha256 hex string
     */
    private String createItemHash(String itemId) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] hash = digest.digest(itemId.getBytes(StandardCharsets.UTF_8));
            StringBuilder sb = new StringBuilder(hash.length * 2);
            for (byte b : hash) {
                sb.append(String.format("%02x", b));
            }
            return sb.toString();
        } catch (Exception e) {
            throw new RuntimeException("Failed to create item hash", e);
        }
    }

    /**
     * Get all items from database.
     *
     * @return list of all items
     */
    private List<StoreItem> getAllItems() {
        List<StoreItem> items = new ArrayList<>();
        String sql = "SELECT namespace, key_name, value_json, created_at, updated_at FROM " + tableName;

        try (Connection conn = dataSource.getConnection();
             Statement stmt = conn.createStatement();
             ResultSet rs = stmt.executeQuery(sql)) {

            while (rs.next()) {
                try {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Inspect the chained cause to see whether it is NoSuchAlgorithmException or a serialization error.
2. Use a standard JDK 17 runtime with default JCE providers.
3. If serialization of namespace fails, ensure namespace components are JSON-serializable strings.
4. Fix the StoreItem data producing invalid hash input rather than catching around every call.

Example fix

// before
StoreItem item = store.getItem(List.of(nsObj), key); // nsObj not serializable
// after
StoreItem item = store.getItem(List.of(String.valueOf(nsObj)), key);

try {
    java.security.MessageDigest.getInstance("SHA-256");
} catch (java.security.NoSuchAlgorithmException e) {
    throw new IllegalStateException("SHA-256 unavailable - DatabaseStore cannot run on this JVM");
}

try { store.getItem(ns, key); } catch (RuntimeException e) { if (e.getMessage().contains("item hash")) log.error("hash failure: {}", e.getCause()); throw e; }

When it happens

Trigger: Calling putItem/getItem/deleteItem when MessageDigest SHA-256 is unavailable in the JVM, or hashing input cannot be processed (e.g., unusual namespace serialization failure).

Common situations: Running on a restricted JDK without the SHA-256 algorithm (rare, e.g., stripped JRE or custom crypto policy); corrupted namespace objects causing serialization exceptions inside the hash routine.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Schema validation failed:
• Failed to create parallel node action for target:
• Failed to create node action for nodeId:
• item cannot be null
• namespace cannot be null

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