flarum/framework · error · ValidationFailed

The prefix should be no longer than $maxPrefix characters…

Error message

The prefix should be no longer than $maxPrefix characters on $this->driver.

What it means

ValidationFailed thrown by DatabaseConfig::validate when the prefix is longer than the maximum identifier length the driver allows, as computed by DatabaseRequirements::maxTablePrefixLength(). Long prefixes plus table names can exceed database identifier limits (e.g. MySQL's 64-character names).

Solutions

Shorten the prefix below the driver's maxTablePrefixLength, e.g. 'app_'.
Query DatabaseRequirements::maxTablePrefixLength($driver) and truncate the prefix with substr() to that limit.
Remove the prefix entirely if multi-tenancy is handled another way.

Example fix

// before
$max = DatabaseRequirements::maxTablePrefixLength($driver);
$config = new DatabaseConfig(driver: $driver, ..., prefix: 'very_long_company_project_prefix_');
// after
$max = DatabaseRequirements::maxTablePrefixLength($driver);
$prefix = mb_substr('very_long_company_project_prefix_', 0, $max);
$config = new DatabaseConfig(driver: $driver, ..., prefix: $prefix);

Defensive patterns

Strategy: validation

Validate before calling

$max = DatabaseRequirements::maxTablePrefixLength($driver);
if ($max !== null && strlen($prefix) > $max) {
    $prefix = substr($prefix, 0, $max);
}
$config = new DatabaseConfig(driver: $driver, ..., prefix: $prefix);

Type guard

function prefixFits(string $prefix, string $driver): bool {
    $max = DatabaseRequirements::maxTablePrefixLength($driver);
    return $max === null || strlen($prefix) <= $max;
}

Try / catch

try {
    $config = new DatabaseConfig(...$input);
} catch (ValidationFailed $e) {
    if (str_contains($e->getMessage(), 'no longer than')) {
        $errors['prefix'] = 'Shorten the prefix for this driver.';
    }
}

Prevention

Always truncate prefix input to maxTablePrefixLength in the UI.
Set maxlength on the prefix form field per driver.
Recheck the limit whenever the driver changes.

When it happens

Trigger: Setting a prefix whose strlen() exceeds the driver-specific cap, e.g. a 30+ character prefix on MySQL where the driver limit is 10 or similar.

Common situations: Users pasting long descriptive prefixes like 'mycompany_project_environment_'; generated prefixes from long app names; changing drivers without rechecking the limit (limits differ per driver).

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/7f096660cc8051bd. Report an issue: GitHub.

Appendix: source

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

        }

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

    public function prepare(Paths $paths): void
    {
        if ($this->driver === 'sqlite' && ! file_exists($this->database)) {
            $this->database = str_replace('.sqlite', '', $this->database).'.sqlite';
            touch($paths->base.'/'.$this->database);
        }
    }

    private function driverOptions(): array
    {
        return match ($this->driver) {
            'mysql', 'mariadb' => [
                'host' => $this->host,
                'port' => $this->port,

View on GitHub (pinned to 4b939f6853)