alibaba/spring-ai-alibaba · error · IllegalArgumentException

dbType cannot be null or blank

Error message

dbType cannot be null or blank

What it means

DatabaseStore builds a JDBC URL from connection parameters and first validates them via validateConnectionInfo. This IllegalArgumentException is thrown when the dbType parameter is null or an empty/whitespace-only string, because no dialect or URL prefix can be derived without it.

Source

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

            case "postgresql", "postgres", "pgsql" -> "jdbc:postgresql://" + host + ":" + port + "/" + database;
            case "oracle" -> "jdbc:oracle:thin:@" + host + ":" + port + ":" + database;
            case "h2" -> "jdbc:h2:mem:" + database + ";DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE";
            default -> throw new IllegalArgumentException(
                    "Unsupported dbType: " + dbType + ". Supported values: mysql, postgresql, oracle, h2");
        };
    }

    /**
     * Validate connection parameters for JDBC URL construction.
     *
     * @param dbType   database type
     * @param host     database host
     * @param port     database port
     * @param database database name
     */
    private static void validateConnectionInfo(String dbType, String host, int port, String database) {
        if (dbType == null || dbType.isBlank()) {
            throw new IllegalArgumentException("dbType cannot be null or blank");
        }
        if (host == null || host.isBlank()) {
            throw new IllegalArgumentException("host cannot be null or blank");
        }
        if (port <= 0) {
            throw new IllegalArgumentException("port must be greater than 0");
        }
        if (database == null || database.isBlank()) {
            throw new IllegalArgumentException("database cannot be null or blank");
        }
    }

    /**
     * Resolve table name with backward-compatible default behavior.
     *
     * @param tableName candidate table name
     * @return resolved table name
     */

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set dbType to one of the supported values (H2, MySQL, PostgreSQL, Oracle) in the store configuration
2. Check that the config key or environment variable supplying dbType is present and non-blank before constructing DatabaseStore
3. Fail fast at startup: validate all connection properties before calling buildJdbcUrl

Example fix

// before
DatabaseStore.builder().dbType(config.get("dbType")).build();
// after
String dbType = Objects.requireNonNull(config.get("dbType"), "dbType must be set");
DatabaseStore.builder().dbType(dbType).build();

if (dbType == null || dbType.isBlank()) throw new IllegalArgumentException("dbType must be set before building the store");

boolean hasDbType(java.util.Map<String,String> cfg) { return cfg.get("dbType") != null && !cfg.get("dbType").isBlank(); }

try { store = DatabaseStore.builder().dbType(dbType).build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("dbType")) { log.error("Missing dbType config"); } throw e; }

When it happens

Trigger: Calling buildJdbcUrl (directly or via DatabaseStore configuration) with dbType null or blank, e.g. a missing 'dbType' entry in a config map/properties file that is passed through as null.

Common situations: YAML/properties config omits the database type key; environment variable for DB type not set and defaulted to null; caller passes an uninitialized String variable instead of 'mysql'/'postgresql'/'oracle'/'h2'.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• host cannot be null or blank
• port must be greater than 0
• database cannot be null or blank
• WORKFLOW_CONFIG_ILLEGAL
• 模型缺少 id

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