flarum/framework · error · ValidationFailed

Please specify the schema name.

Error message

Please specify the schema name.

What it means

ValidationFailed thrown by DatabaseConfig::validate when the schema is empty and the driver is PostgreSQL. PostgreSQL organizes tables into schemas (default 'public'), and the installer requires one explicitly. Other drivers do not have this requirement.

Solutions

1. Set the schema property to 'public' (the default PostgreSQL schema) or your custom schema.
2. Ensure the target schema exists in the PostgreSQL database and the user has rights on it.
3. If the driver is not pgsql, ignore — this check only applies to PostgreSQL.

Example fix

// before
new DatabaseConfig(driver: 'pgsql', host: 'db', port: 5432, database: 'app', schema: '');
// after
new DatabaseConfig(driver: 'pgsql', host: 'db', port: 5432, database: 'app', schema: 'public');

if ($driver === 'pgsql' && trim((string) $schema) === '') {
    $schema = 'public';
}
$config = new DatabaseConfig(driver: $driver, host: $host, port: $port, database: $database, schema: $schema);

function hasSchema(array $cfg): bool {
    return $cfg['driver'] !== 'pgsql' || (isset($cfg['schema']) && trim((string) $cfg['schema']) !== '');
}

try {
    $config = new DatabaseConfig(...$input);
} catch (ValidationFailed $e) {
    if (str_contains($e->getMessage(), 'schema')) {
        $errors['schema'] = "PostgreSQL requires a schema (use 'public').";
    }
}

When it happens

Trigger: Constructing DatabaseConfig with driver 'pgsql' and an empty schema property.

Common situations: MySQL-to-PostgreSQL migration where the schema field was never filled; .env missing DB_SCHEMA equivalent; users unaware PostgreSQL needs a schema; private-schema setups where the default 'public' was removed.

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 hostname of your database server.
• Please provide a valid port number between 1 and 65535.
• Please specify the database name.
• Please specify the username for accessing the database.
• PostgreSQL version ($version) too low. You need at least…

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

Appendix: source

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

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

View on GitHub (pinned to 4b939f6853)