alibaba/spring-ai-alibaba · error · IllegalArgumentException

database cannot be null or blank

Error message

database cannot be null or blank

What it means

Configuration validation failure in DatabaseStore.validateConnectionInfo, a private precondition helper called from buildJdbcUrl. The database name is a required segment of the JDBC URL; when it is null or blank IllegalArgumentException is thrown while constructing the URL at store initialization. This signals missing database configuration rather than a connectivity issue; set the database name in the DatabaseStore connection settings.

Source

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

     * 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
     */
    private static String resolveTableName(String tableName) {
        if (tableName == null || tableName.isBlank()) {
            return DEFAULT_TABLE_NAME;
        }
        return tableName;
    }

    /**
     * Minimal JDBC DataSource implementation based on DriverManager.

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set the target database/schema name in the store configuration
2. Confirm the database actually exists on the server with that name
3. Validate that the config key supplying the database name is non-blank before initialization

Example fix

// before
.database(cfg.getOrDefault("db.name", ""))
// after
String dbName = cfg.getProperty("db.name");
if (dbName == null || dbName.isBlank()) throw new IllegalStateException("db.name must be set");
.database(dbName)

if (database == null || database.isBlank()) throw new IllegalArgumentException("database name must be configured");

boolean hasDatabase(java.util.Map<String,String> cfg) { String d = cfg.get("db.name"); return d != null && !d.isBlank(); }

try { store = DatabaseStore.builder().database(db).build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("database")) { log.error("Database name missing"); } throw e; }

When it happens

Trigger: Calling buildJdbcUrl with database == null or blank, e.g. the database name key absent from config or the caller passing an empty string after sanitization.

Common situations: New environment provisioned without creating/setting the database name; config template placeholder never filled in; empty value produced by a CI variable substitution.

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

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

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