laravel/framework · error · RuntimeException

This database engine does not support JSON length operations

Error message

This database engine does not support JSON length operations.

What it means

The base Grammar::compileJsonLength() throws because this engine has no JSON length function mapping. All four bundled grammars (SQLite, MySQL, Postgres, SQL Server) override compileJsonLength, so the base throw is only hit by a custom Grammar subclass that does not implement JSON length.

Source

Thrown at src/Illuminate/Database/Query/Grammars/Grammar.php:812

            $where['column'],
            $where['operator'],
            $this->parameter($where['value'])
        );
    }

    /**
     * Compile a "JSON length" statement into SQL.
     *
     * @param  string  $column
     * @param  string  $operator
     * @param  string  $value
     * @return string
     *
     * @throws \RuntimeException
     */
    protected function compileJsonLength($column, $operator, $value)
    {
        throw new RuntimeException('This database engine does not support JSON length operations.');
    }

    /**
     * Compile a "JSON value cast" statement into SQL.
     *
     * @param  string  $value
     * @return string
     */
    public function compileJsonValueCast($value)
    {
        return $value;
    }

    /**
     * Compile a "where fulltext" clause.
     *
     * @param  \Illuminate\Database\Query\Builder  $query
     * @param  array  $where

View on GitHub (pinned to bd6b5437e6)

Solutions

Implement compileJsonLength($column, $operator, $value) on the custom Grammar using the engine's native JSON length function.
Switch to a bundled driver that supports JSON length operations.
Substitute whereRaw with the native JSON length function for the specific engine.

Example fix

// before (custom grammar missing impl)
$q->whereJsonLength('meta->items', '>', 3);

// after
protected function compileJsonLength($column, $operator, $value)
{
    return "json_length({$column}) {$operator} {$value}";
}

Defensive patterns

Strategy: validation

Validate before calling

$driver = $query->getConnection()->getDriverName();
if (! in_array($driver, ['mysql','sqlite','pgsql','sqlsrv'])) {
    throw new \LogicException('whereJsonLength is not supported by this engine.');
}
$query->whereJsonLength('meta->items', '>', 3);

Type guard

function supportsJsonLength(\Illuminate\Database\Connection $connection): bool
{
    return method_exists($connection->getQueryGrammar(), 'compileJsonLength');
}

Prevention

Implement compileJsonLength on any custom grammar.
Keep JSON length checks on bundled drivers.
Cover JSON methods in driver capability tests.

When it happens

Trigger: Calling whereJsonLength($column, $operator, $value) on a connection whose grammar extends the base Grammar without overriding compileJsonLength. None of the bundled drivers reach this base method.

Common situations: A custom/third-party grammar integration that is missing JSON length support. Building a new driver and forgetting to implement the JSON where-clause family.

Related errors

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