alibaba/spring-ai-alibaba · error · IllegalArgumentException

port must be greater than 0

Error message

port must be greater than 0

What it means

Configuration validation failure in DatabaseStore.validateConnectionInfo, a private precondition helper called from buildJdbcUrl. The port must be a positive number to appear in a valid JDBC URL; a non-positive port means the DatabaseStore connection settings are misconfigured, so IllegalArgumentException is thrown during URL construction at startup. Fix the configured port (e.g., 3306 for MySQL, 5432 for PostgreSQL, 1521 for Oracle).

Source

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

    }

    /**
     * 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;
    }

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set the correct port for the dialect (e.g. 3306 MySQL, 5432 PostgreSQL, 1521 Oracle)
2. Ensure the port config value is parsed as an int and is > 0 before calling buildJdbcUrl
3. Check for default-to-zero behavior when a config key is missing

Example fix

// before
int port = Integer.parseInt(cfg.getProperty("db.port", "0"));
// after
int port = Integer.parseInt(cfg.getProperty("db.port", "5432"));
if (port <= 0) throw new IllegalArgumentException("db.port must be > 0");

if (port <= 0 || port > 65535) throw new IllegalArgumentException("db.port must be in 1..65535");

boolean isValidPort(int port) { return port > 0 && port <= 65535; }

try { store = DatabaseStore.builder().port(port).build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("port")) { log.error("Invalid port: " + port); } throw e; }

When it happens

Trigger: Calling buildJdbcUrl with port 0 or negative — often the result of an unset numeric config that defaults to 0 or a failed Integer.parseInt fallback.

Common situations: Port placeholder left as 0 in config; properties binding failure where a string port was not parsed; copying an example without replacing the port.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• dbType cannot be null or blank
• host cannot be null or blank
• 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/c6420de5195525ec. Report an issue: GitHub.