flarum/framework · error · ValidationFailed

Please specify the username for accessing the database.

Error message

Please specify the username for accessing the database.

What it means

ValidationFailed thrown by DatabaseConfig::validate when the username is empty for mysql, mariadb or pgsql. These drivers authenticate over the connection, so a username is mandatory; SQLite does not need one.

Solutions

1. Set the username property (or DB_USER) to a database user with privileges on the target database.
2. Create a dedicated database user and grant it the needed permissions.
3. Use the SQLite driver if no credentials should be required.

Example fix

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

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

function hasUsername(array $cfg): bool {
    return $cfg['driver'] === 'sqlite' || (isset($cfg['username']) && trim((string) $cfg['username']) !== '');
}

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

When it happens

Trigger: Constructing DatabaseConfig with a TCP driver and empty username property (missing DB_USER).

Common situations: Install form with blank username; .env missing DB_USER; user assumed root/trusted auth; copy-pasted sqlite config used for MySQL.

Related errors

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

Appendix: source

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

        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) {
                throw new ValidationFailed("The prefix should be no longer than $maxPrefix characters on $this->driver.");
            }
        }
    }

    public function prepare(Paths $paths): void
    {
        if ($this->driver === 'sqlite' && ! file_exists($this->database)) {

View on GitHub (pinned to 4b939f6853)