laravel/framework · error · InvalidArgumentException

The seed value must be numeric.

Error message

The seed value must be numeric.

What it means

MySqlGrammar::compileRandom() throws InvalidArgumentException when a seed is supplied that is not numeric. MySQL's RAND(n) only accepts a numeric seed; passing a string seed produces invalid SQL, so Laravel rejects it before compilation. An empty/null seed is allowed and produces RAND() with no argument.

Source

Thrown at src/Illuminate/Database/Query/Grammars/MySqlGrammar.php:347

        return 'cast('.$value.' as json)';
    }

    /**
     * Compile the random statement into SQL.
     *
     * @param  string|int  $seed
     * @return string
     *
     * @throws \InvalidArgumentException
     */
    public function compileRandom($seed)
    {
        if ($seed === '' || $seed === null) {
            return 'RAND()';
        }

        if (! is_numeric($seed)) {
            throw new InvalidArgumentException('The seed value must be numeric.');
        }

        return 'RAND('.(int) $seed.')';
    }

    /**
     * Compile the lock into SQL.
     *
     * @param  \Illuminate\Database\Query\Builder  $query
     * @param  bool|string  $value
     * @return string
     */
    protected function compileLock(Builder $query, $value)
    {
        if (! is_string($value)) {
            return $value ? 'for update' : 'lock in share mode';
        }

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Pass an integer seed (e.g. crc32 of the string) to RAND() for deterministic ordering.
2. Call inRandomOrder() with no argument for non-deterministic shuffling.
3. Sanitize the seed: cast with (int) or validate with is_numeric() before calling.

Example fix

// before
$query->inRandomOrder($request->input('seed'));

// after
$seed = $request->input('seed');
$query->inRandomOrder(is_numeric($seed) ? (int) $seed : (empty($seed) ? '' : crc32($seed)));

$seed = $request->input('seed');
if ($seed !== '' && $seed !== null && ! is_numeric($seed)) {
    throw new \InvalidArgumentException('inRandomOrder seed must be numeric on MySQL.');
}
$query->inRandomOrder($seed);

function isValidMysqlSeed(mixed $seed): bool
{
    return $seed === '' || $seed === null || is_numeric($seed);
}

When it happens

Trigger: Calling inRandomOrder($seed) where $seed is a non-numeric, non-empty string (e.g. 'abc' or a UUID) on a MySQL/MariaDB connection. The error occurs when compileRandom builds the ORDER BY RAND(seed) SQL.

Common situations: Passing a request token or hash string as a random seed for reproducible shuffling. Reusing a string identifier from another engine's seed semantics on MySQL.

Related errors

• Index name contains invalid characters.
• The given password does not match the current password.
• You requested {$requested} items, but there are only {$count
• $count items were found.
• Step value must be at least 1.

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/e621b23ecc9b6027.json. Report an issue: GitHub.