alibaba/spring-ai-alibaba · error · IllegalArgumentException

host cannot be null or blank

Error message

host cannot be null or blank

What it means

Configuration validation failure in DatabaseStore.validateConnectionInfo, a private precondition helper called from buildJdbcUrl. The JDBC URL cannot be constructed without a host, so when the configured host is null or blank IllegalArgumentException is thrown at store initialization, before any connection is attempted. This indicates a misconfigured DatabaseStore (missing host in its connection settings) rather than a runtime connectivity problem; fix the configuration.

Source

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

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

View on GitHub (pinned to f82da0b50f)

Solutions

1. Provide the database host (e.g. localhost or the DB service hostname) in the store configuration
2. Verify the environment variable/config key that supplies the host is populated
3. Add a startup check that all connection fields are non-blank before creating the store

Example fix

// before
.host(env.getProperty("db.host")) // may be null
// after
String host = env.getRequiredProperty("db.host");
.host(host)

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

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

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

When it happens

Trigger: Calling buildJdbcUrl with host == null or host.isBlank(), typically because the host config key was not provided or was trimmed to an empty string.

Common situations: Deployment config lacks the DB host entry; using a container where the DB_HOST env var is unset; copy-pasted config where hostname was accidentally deleted.

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
• 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/710f0d8d6e050c84. Report an issue: GitHub.