flarum/framework · error · ValidationFailed

Please provide a valid port number between 1 and 65535.

Error message

Please provide a valid port number between 1 and 65535.

What it means

ValidationFailed thrown by DatabaseConfig::validate when the port is outside 1-65535 for mysql, mariadb or pgsql drivers. It ensures the port is a usable TCP port number before the installer attempts a connection. SQLite again is exempt since it does not connect over TCP.

Solutions

1. Set the port to the correct server port: 3306 for MySQL/MariaDB, 5432 for PostgreSQL.
2. If the env value may be blank, apply the driver default before constructing DatabaseConfig.
3. Cast/validate the value as an integer in (1..65535) before passing it in.
4. Switch to sqlite driver if no TCP database is intended.

Example fix

// before
new DatabaseConfig(driver: 'mysql', host: 'db', port: 0, database: 'app');
// after
new DatabaseConfig(driver: 'mysql', host: 'db', port: 3306, database: 'app');

$port = (int) ($env['DB_PORT'] ?: match($driver) { 'pgsql' => 5432, default => 3306 });
if ($port < 1 || $port > 65535) {
    throw new InvalidArgumentException('DB_PORT must be between 1 and 65535');
}
$config = new DatabaseConfig(driver: $driver, host: $host, port: $port, database: $database);

function isValidPort(mixed $port): bool {
    return is_int($port) && $port >= 1 && $port <= 65535;
}

try {
    $config = new DatabaseConfig(...$input);
} catch (ValidationFailed $e) {
    if (str_contains($e->getMessage(), 'port')) {
        $errors['port'] = 'Use 3306 (MySQL/MariaDB) or 5432 (PostgreSQL).';
    }
}

When it happens

Trigger: Constructing DatabaseConfig with a port of 0, negative, >65535, or an unset/null port for a TCP-based driver.

Common situations: DB_PORT env var left empty or set to a non-numeric placeholder; typo like 3306033; copying a redis (6379) or http (80) port into the DB config; missing default when the form field is blank.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Please specify the hostname of your database server.
• Please specify the database name.
• Please specify the username for accessing the database.
• Please specify a database driver.
• Please specify the schema name.

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/221493aa086a3751. Report an issue: GitHub.

Appendix: source

Thrown at framework/core/src/Install/DatabaseConfig.php:56

        ], $this->driverOptions());
    }

    private function validate(): void
    {
        if (empty($this->driver)) {
            throw new ValidationFailed('Please specify a database driver.');
        }

        if (! in_array($this->driver, ['mysql', 'mariadb', 'sqlite', 'pgsql'])) {
            throw new ValidationFailed('Currently, only MySQL, MariaDB, SQLite and PostgreSQL are supported.');
        }

        if (empty($this->host) && in_array($this->driver, ['mysql', 'mariadb', 'pgsql'])) {
            throw new ValidationFailed('Please specify the hostname of your database server.');
        }

        if (($this->port < 1 || $this->port > 65535) && in_array($this->driver, ['mysql', 'mariadb', 'pgsql'])) {
            throw new ValidationFailed('Please provide a valid port number between 1 and 65535.');
        }

        if (empty($this->database)) {
            throw new ValidationFailed('Please specify the database name.');
        }

        if (empty($this->schema) && $this->driver == 'pgsql') {
            throw new ValidationFailed('Please specify the schema name.');
        }

        if (empty($this->username) && in_array($this->driver, ['mysql', 'mariadb', 'pgsql'])) {
            throw new ValidationFailed('Please specify the username for accessing the database.');
        }

        if (! empty($this->prefix)) {
            if (! preg_match('/^[\pL\pM\pN_]+$/u', $this->prefix)) {
                throw new ValidationFailed('The prefix may only contain characters and underscores.');
            }

View on GitHub (pinned to 4b939f6853)