flarum/framework · error · ValidationFailed

Please specify the database name.

Error message

Please specify the database name.

What it means

ValidationFailed thrown by DatabaseConfig::validate when the database name is empty. Unlike host/port, this applies to every driver including SQLite (where it is the database file path). The installer refuses to proceed without knowing which database to create/use.

Solutions

1. Set the database property (or DB_DATABASE) to an existing database name the user can access.
2. Create the database on the server first, then supply its name.
3. For SQLite, set the database to the path of the .sqlite file to use.

Example fix

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

if (trim((string) $database) === '') {
    throw new InvalidArgumentException('DB_DATABASE is required');
}
$config = new DatabaseConfig(driver: $driver, host: $host, port: $port, database: $database);

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

try {
    $config = new DatabaseConfig(...$input);
} catch (ValidationFailed $e) {
    if (str_contains($e->getMessage(), 'database name')) {
        $errors['database'] = 'Database name is required.';
    }
}

When it happens

Trigger: Constructing DatabaseConfig with an empty database name/path for any driver, e.g. missing DB_DATABASE value.

Common situations: Install form submitted with blank database field; .env missing DB_DATABASE; user expects the DB to be auto-created from a project name; SQLite path field left empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Please specify the hostname of your database server.
• 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/d3f9f4dff4bcf98a. Report an issue: GitHub.

Appendix: source

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

    {
        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.');
            }

            $maxPrefix = DatabaseRequirements::maxTablePrefixLength($this->driver);

            if ($maxPrefix !== null && strlen($this->prefix) > $maxPrefix) {

View on GitHub (pinned to 4b939f6853)