flarum/framework · error · RangeException

MySQL version ($version) too low. You need at least MySQL

Error message

MySQL version ($version) too low. You need at least MySQL 

What it means

Flarum's ConnectToDatabase install step queries the connected MySQL server's version and throws a RangeException when it is older than the minimum supported version (DatabaseRequirements::MYSQL_MINIMUM). The library refuses to install against databases it cannot support, since older servers lack required SQL features. The message includes the detected version so you can see how far behind you are.

Solutions

1. Upgrade the MySQL server to at least the version in DatabaseRequirements::MYSQL_MINIMUM
2. If you actually run MariaDB, set the driver to `mariadb` so the MariaDB minimum and connector are used instead
3. Migrate to a managed database offering a supported MySQL version
4. Check `SELECT VERSION()` on the server to confirm what version is really being reported

Example fix

// before (config.php)
'driver' => 'mysql', // hits MySQL 5.7 server
// after
'driver' => 'mysql', // after upgrading server to MySQL 8.0+, or:
'driver' => 'mariadb',

$version = DB::selectOne('SELECT VERSION()')->{'VERSION()'};
if (version_compare($version, '8.0', '<')) { /* abort install / warn */ }

try { $step->run($dbConfig); } catch (RangeException $e) { log($e->getMessage()); abort with 'database version unsupported' UI message; }

When it happens

Trigger: Running the Flarum installer (`php flarum install` or web installer) with the `mysql` driver selected while the connected server reports a version below the hardcoded MYSQL_MINIMUM constant after normalisation via DatabaseRequirements::normaliseVersion().

Common situations: Pointing Flarum at a legacy shared-hosting MySQL 5.6/5.7 server; Docker images pinned to old MySQL tags; hosting providers that haven't upgraded; misconfigured proxies exposing an old replica.

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

• PostgreSQL version ($version) too low. You need at least…
• SQLite version ($version) too low. You need at least SQLite…
• Please specify a database driver.
• Currently, only MySQL, MariaDB, SQLite and PostgreSQL are…
• You must enter a valid email.

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

Appendix: source

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

    }

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

        $raw = $pdo->query('SELECT VERSION()')->fetchColumn();

        if (DatabaseRequirements::isMariaDb($raw)) {
            $version = DatabaseRequirements::normaliseVersion($raw, true) ?? $raw;

            if (version_compare($version, DatabaseRequirements::MARIADB_MINIMUM, '<')) {
                throw new RangeException("MariaDB version ($version) too low. You need at least MariaDB ".DatabaseRequirements::MARIADB_MINIMUM);
            }
        } else {
            $version = DatabaseRequirements::normaliseVersion($raw, false) ?? $raw;

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

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

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

        $raw = $pdo->query('SELECT VERSION()')->fetchColumn();

View on GitHub (pinned to 4b939f6853)