flarum/framework · error · RangeException

PostgreSQL version ($version) too low. You need at least…

Error message

PostgreSQL version ($version) too low. You need at least PostgreSQL 10

What it means

Flarum's PostgreSQL install path queries SHOW server_version, trims any suffix via Str::before($version, ' '), and throws a RangeException when it is older than DatabaseRequirements::PGSQL_MINIMUM (PostgreSQL 10). Flarum requires modern Postgres features unavailable in 9.x. The message includes the actual detected version.

Solutions

Upgrade PostgreSQL to 10 or later (preferably a supported major like 14+), e.g. via pg_upgrade
Point Flarum at a newer managed PostgreSQL instance
If upgrading is impossible, choose a different supported driver (MySQL 8+/MariaDB/SQLite) for this install

Example fix

// before
'driver' => 'pgsql', // Postgres 9.6
// after
'driver' => 'pgsql', // after pg_upgrade to PostgreSQL 14
// or
'driver' => 'mysql',

Defensive patterns

Strategy: validation

Validate before calling

$v = DB::selectOne('SHOW server_version')->server_version;
if (version_compare(Str::before($v, ' '), '10', '<')) { /* abort install */ }

Try / catch

try { $step->run($dbConfig); } catch (RangeException $e) { report($e); show('PostgreSQL 10+ required'); }

Prevention

Upgrade EOL managed Postgres instances (RDS/Azure 9.6 -> 12+)
Run pg_upgrade as part of environment modernisation
Prefer currently supported Postgres majors (12+)

When it happens

Trigger: Running the installer with driver `pgsql` against a PostgreSQL 9.x server (or a server whose reported version string normalises below 10).

Common situations: Legacy RDS/Azure Postgres 9.6 instances; old self-hosted Postgres from distro repos; connecting to a deprecated managed instance that was never upgraded.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at framework/core/src/Install/Steps/ConnectToDatabase.php:114

        ($this->store)(
            new MariaDbConnection(
                $pdo,
                $config['database'],
                $config['prefix'],
                $config
            )
        );
    }

    private function pgsql(array $config): void
    {
        $pdo = (new PostgresConnector)->connect($config);

        $version = $pdo->query('SHOW server_version')->fetchColumn();
        $version = Str::before($version, ' ');

        if (version_compare($version, DatabaseRequirements::PGSQL_MINIMUM, '<')) {
            throw new RangeException("PostgreSQL version ($version) too low. You need at least PostgreSQL 10");
        }

        ($this->store)(
            new PostgresConnection(
                $pdo,
                $config['database'],
                $config['prefix'],
                $config
            )
        );
    }

    private function sqlite(array $config): void
    {
        if (! file_exists($config['database'])) {
            $config['database'] = $this->basePath.'/'.$config['database'];
        }

View on GitHub (pinned to 4b939f6853)