{"record":{"id":"e9e84a1abb7bb059","repo":"flarum/framework","slug":"please-specify-the-username-for-accessing-the-database","errorCode":null,"errorMessage":"Please specify the username for accessing the database.","messagePattern":"Please specify the username for accessing the database\\.","errorType":"validation","errorClass":"ValidationFailed","httpStatus":null,"severity":"error","filePath":"framework/core/src/Install/DatabaseConfig.php","lineNumber":68,"sourceCode":"\n        if (empty($this->host) && in_array($this->driver, ['mysql', 'mariadb', 'pgsql'])) {\n            throw new ValidationFailed('Please specify the hostname of your database server.');\n        }\n\n        if (($this->port < 1 || $this->port > 65535) && in_array($this->driver, ['mysql', 'mariadb', 'pgsql'])) {\n            throw new ValidationFailed('Please provide a valid port number between 1 and 65535.');\n        }\n\n        if (empty($this->database)) {\n            throw new ValidationFailed('Please specify the database name.');\n        }\n\n        if (empty($this->schema) && $this->driver == 'pgsql') {\n            throw new ValidationFailed('Please specify the schema name.');\n        }\n\n        if (empty($this->username) && in_array($this->driver, ['mysql', 'mariadb', 'pgsql'])) {\n            throw new ValidationFailed('Please specify the username for accessing the database.');\n        }\n\n        if (! empty($this->prefix)) {\n            if (! preg_match('/^[\\pL\\pM\\pN_]+$/u', $this->prefix)) {\n                throw new ValidationFailed('The prefix may only contain characters and underscores.');\n            }\n\n            $maxPrefix = DatabaseRequirements::maxTablePrefixLength($this->driver);\n\n            if ($maxPrefix !== null && strlen($this->prefix) > $maxPrefix) {\n                throw new ValidationFailed(\"The prefix should be no longer than $maxPrefix characters on $this->driver.\");\n            }\n        }\n    }\n\n    public function prepare(Paths $paths): void\n    {\n        if ($this->driver === 'sqlite' && ! file_exists($this->database)) {","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/flarum/framework/blob/4b939f685389bfe8a380e9e28ddf305a1c66950c/framework/core/src/Install/DatabaseConfig.php#L50-L86","documentation":"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.","triggerScenarios":"Constructing DatabaseConfig with a TCP driver and empty username property (missing DB_USER).","commonSituations":"Install form with blank username; .env missing DB_USER; user assumed root/trusted auth; copy-pasted sqlite config used for MySQL.","solutions":["Set the username property (or DB_USER) to a database user with privileges on the target database.","Create a dedicated database user and grant it the needed permissions.","Use the SQLite driver if no credentials should be required."],"exampleFix":"// before\nnew DatabaseConfig(driver: 'mysql', host: 'db', port: 3306, database: 'app', username: '');\n// after\nnew DatabaseConfig(driver: 'mysql', host: 'db', port: 3306, database: 'app', username: 'flarum');","handlingStrategy":"validation","validationCode":"if (in_array($driver, ['mysql','mariadb','pgsql'], true) && trim((string) $username) === '') {\n    throw new InvalidArgumentException('DB username is required for '.$driver);\n}\n$config = new DatabaseConfig(driver: $driver, host: $host, port: $port, database: $database, username: $username);","typeGuard":"function hasUsername(array $cfg): bool {\n    return $cfg['driver'] === 'sqlite' || (isset($cfg['username']) && trim((string) $cfg['username']) !== '');\n}","tryCatchPattern":"try {\n    $config = new DatabaseConfig(...$input);\n} catch (ValidationFailed $e) {\n    if (str_contains($e->getMessage(), 'username')) {\n        $errors['username'] = 'A database username is required.';\n    }\n}","preventionTips":["Require the username field for TCP drivers in installer forms.","Keep DB_USER in .env templates with a placeholder to notice omissions.","Provision the DB user as part of deployment scripts."],"tags":["database","config","credentials","validation"],"backgroundTag":"missing-credentials","analyzedSha":"4b939f685389bfe8a380e9e28ddf305a1c66950c","analyzedAt":"2026-09-15T18:09:20.879Z","contentChangedAt":"2026-09-15T18:09:20.879Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}