flarum/framework · error · ValidationFailed

Please specify the hostname of your database server.

Error message

Please specify the hostname of your database server.

What it means

ValidationFailed thrown by DatabaseConfig::validate during installation when the database host is empty for a network-based driver. SQLite is file-based and needs no host, but MySQL, MariaDB and PostgreSQL require a server hostname. The check runs in the constructor, so invalid config fails fast before any connection is attempted.

Solutions

1. Set the host property (or DB_HOST env) to your database server hostname or IP before constructing DatabaseConfig.
2. Use 'localhost' or '127.0.0.1' if the database runs on the same machine.
3. If you intend to use SQLite, switch the driver to 'sqlite' so the host check is skipped.

Example fix

// before
new DatabaseConfig(driver: 'mysql', host: '', database: 'flarum');
// after
new DatabaseConfig(driver: 'mysql', host: '127.0.0.1', database: 'flarum');

if (in_array($driver, ['mysql','mariadb','pgsql'], true) && trim((string) $host) === '') {
    throw new InvalidArgumentException('DB host is required for '.$driver);
}
$config = new DatabaseConfig(driver: $driver, host: $host, database: $database);

function hasHost(array $cfg): bool {
    return isset($cfg['host']) && is_string($cfg['host']) && trim($cfg['host']) !== '';
}

try {
    $config = new DatabaseConfig(...$input);
} catch (ValidationFailed $e) {
    if (str_contains($e->getMessage(), 'hostname')) {
        $errors['host'] = 'Hostname is required for this driver.';
    }
}

When it happens

Trigger: Constructing DatabaseConfig with driver mysql/mariadb/pgsql and an empty or unset host property (e.g. missing DB_HOST in the installer form or config).

Common situations: Install wizard where the hostname field was left blank; .env with DB_HOST missing; copying a sqlite-oriented config to a MySQL install; localhost configured only for the sqlite driver.

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

• Please specify the database name.
• Please provide a valid port number between 1 and 65535.
• 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/f39935f8239be552. Report an issue: GitHub.

Appendix: source

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

            'driver' => $this->driver,
            'database' => $this->database,
            'prefix' => $this->prefix,
            'prefix_indexes' => true
        ], $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.');
        }

View on GitHub (pinned to 4b939f6853)