flarum/framework · error · RangeException

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

Error message

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

What it means

RangeException from ConnectToDatabase::mysql when the connected server reports a MariaDB version below DatabaseRequirements::MARIADB_MINIMUM. After connecting, the step runs SELECT VERSION(); if the raw string identifies MariaDB, its normalized version is compared against the minimum and the install aborts. (Its sibling branch throws the equivalent error for MySQL below MYSQL_MINIMUM.)

Solutions

Upgrade the MariaDB server to at least the version in DatabaseRequirements::MARIADB_MINIMUM (e.g. via the official MariaDB repository).
Point DB_HOST at a newer server/container (e.g. mariadb:10.11 image).
If upgrading is impossible, use a hosting provider or container with a supported version.
Check your current version with SELECT VERSION(); before installing.

Example fix

// before
docker run -d mariadb:10.2   # too old
// after
docker run -d mariadb:10.11  # >= DatabaseRequirements::MARIADB_MINIMUM

Defensive patterns

Strategy: validation

Validate before calling

$version = $pdo->query('SELECT VERSION()')->fetchColumn();
if (DatabaseRequirements::isMariaDb($version)) {
    $norm = DatabaseRequirements::normaliseVersion($version, true);
    if (version_compare($norm, DatabaseRequirements::MARIADB_MINIMUM, '<')) {
        throw new RuntimeException("Upgrade MariaDB: have {$norm}, need ".DatabaseRequirements::MARIADB_MINIMUM);
    }
}

Type guard

function meetsMinVersion(string $raw, string $min, bool $maria): bool {
    $v = DatabaseRequirements::normaliseVersion($raw, $maria) ?? $raw;
    return version_compare($v, $min, '>=');
}

Try / catch

try {
    $step->run($config);
} catch (RangeException $e) {
    if (str_contains($e->getMessage(), 'too low')) {
        $errors['db'] = $e->getMessage().' — upgrade your database server.';
    }
}

Prevention

Pin container images to a version >= the app's minimum requirement.
Run SELECT VERSION() as an install pre-flight check.
Subscribe to minimum-version changes when upgrading the application.
Use distro repos that ship current MariaDB versions (official MariaDB repo).

When it happens

Trigger: Connecting to a MariaDB server older than the required minimum (per DatabaseRequirements::MARIADB_MINIMUM) during the ConnectToDatabase install step.

Common situations: Old distro packages (e.g. MariaDB 10.1/10.2 on legacy Ubuntu/CentOS); managed hosting with fixed old versions; local dev using an outdated MariaDB container image; upgrades of the app raising the minimum requirement.

Related errors

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

Appendix: source

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

            'mysql' => $this->mysql($config),
            'mariadb' => $this->mariadb($config),
            'pgsql' => $this->pgsql($config),
            'sqlite' => $this->sqlite($config),
            default => throw new InvalidArgumentException('Unsupported database driver: '.$config['driver']),
        };
    }

    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
            )
        );
    }

View on GitHub (pinned to 4b939f6853)