alibaba/spring-ai-alibaba · error · UnsupportedOperationException

Unsupported database dialect

Error message

Unsupported database dialect: {dialect}. Supported dialects: H2, MySQL, PostgreSQL, Oracle

What it means

executeUpsert switches on the detected/declared database dialect; when the dialect resolves to OTHER (not one of H2, MySQL, PostgreSQL, Oracle) it throws UnsupportedOperationException with this message. The store only has vendor-specific UPSERT implementations for those four databases.

Solutions

Use one of the supported dialects: H2, MySQL, PostgreSQL, or Oracle
Check the exact dbType string/driver the store detects from the JDBC URL and correct it (e.g. 'postgresql')
If your DB is MySQL-compatible, force the MySQL dialect in configuration instead of relying on auto-detection

Example fix

// before
DatabaseStore.builder().dbType("mariadb").build();
// after
DatabaseStore.builder().dbType("mysql").build(); // MySQL-compatible upsert syntax

Defensive patterns

Strategy: validation

Validate before calling

java.util.Set<String> supported = java.util.Set.of("h2","mysql","postgresql","oracle");
if (!supported.contains(dbType.toLowerCase())) throw new IllegalArgumentException("Unsupported dbType: " + dbType);

Type guard

boolean isSupportedDialect(String dbType) { return dbType != null && java.util.Set.of("h2","mysql","postgresql","oracle").contains(dbType.toLowerCase()); }

Try / catch

try { store.putItem(item); } catch (UnsupportedOperationException e) { if (e.getMessage().startsWith("Unsupported database dialect")) { log.error("Switch to H2/MySQL/PostgreSQL/Oracle or force a compatible dialect"); } throw e; }

Prevention

Verify dialect auto-detection against your actual DB vendor (MariaDB is not auto-mapped)
Use an allow-list enum for dbType in configuration
Test store writes against the target database in CI before deploying

When it happens

Trigger: Configuring DatabaseStore with a dbType/jdbcUrl whose dialect cannot be mapped (e.g. MariaDB reported as OTHER, SQL Server, SQLite, or a misspelled dbType string), then calling putItem.

Common situations: Using a database that speaks a MySQL-like protocol but identifies differently (MariaDB); unsupported DB chosen because 'it's just SQL'; typo in dbType such as 'postgres' vs expected spelling that fails dialect detection.

Related errors

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

     * @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
     */
    private void executeUpsert(Connection conn, String itemId, String itemHash, String namespaceJson, String key, String valueJson,
                               Timestamp createdAt, Timestamp updatedAt) throws SQLException {
        DatabaseDialect dialect = getDatabaseDialect(conn);
        switch (dialect) {
            case H2 -> executeH2Merge(conn, itemId, itemHash, namespaceJson, key, valueJson, createdAt, updatedAt);
            case MYSQL -> executeMysqlUpsert(conn, itemId, itemHash, namespaceJson, key, valueJson, createdAt, updatedAt);
            case POSTGRESQL -> executePostgresqlUpsert(conn, itemId, itemHash, namespaceJson, key, valueJson, createdAt,
                    updatedAt);
            case ORACLE -> executeOracleUpsert(conn, itemId, itemHash, namespaceJson, key, valueJson, createdAt, updatedAt);
            case OTHER -> throw new UnsupportedOperationException(
                    "Unsupported database dialect: " + dialect + ". Supported dialects: H2, MySQL, PostgreSQL, Oracle");
        }
    }

    /**
     * H2 database UPSERT implementation using MERGE INTO syntax.
     *
     * @param conn          database connection
     * @param itemId        unique primary key
     * @param namespaceJson serialized namespace
     * @param key           business key
     * @param valueJson     serialized value
     * @param createdAt     created timestamp
     * @param updatedAt     updated timestamp
     * @throws SQLException if SQL execution fails
     */
    private void executeH2Merge(Connection conn, String itemId, String itemHash, String namespaceJson, String key, String valueJson,
                                Timestamp createdAt, Timestamp updatedAt) throws SQLException {

View on GitHub (pinned to f82da0b50f)