laravel/framework · error · RuntimeException

This database engine does not support JSON length…

Error message

This database engine does not support JSON length operations.

What it means

The base Grammar's compileJsonLength throws by default. All four major engine grammars (MySQL, PostgreSQL, SQLite, SQL Server) override it with engine-specific JSON_ARRAY_LENGTH / jsonb_array_length / json_array_length / OPENJSON functions. This error fires only for a custom grammar extending the base Grammar without an override.

Solutions

Switch to a built-in connection (mysql, pgsql, sqlite, or sqlsrv) — all four override compileJsonLength
Override compileJsonLength in your custom grammar with the correct SQL function for your engine
Replace whereJsonLength with a raw clause, e.g., ->whereRaw('json_array_length(metadata) > ?', [2])

Example fix

// before — custom grammar without JSON length support
DB::table('users')->whereJsonLength('roles', '>', 2)->get();

// after — raw clause for a custom engine
DB::table('users')->whereRaw('json_array_length(roles) > ?', [2])->get();

Defensive patterns

Strategy: try-catch

Validate before calling

$grammar = DB::connection()->getQueryGrammar();
$method = new ReflectionMethod($grammar, 'compileJsonLength');

if ($method->getDeclaringClass()->getName() !== 'Illuminate\\Database\\Query\\Grammars\\Grammar') {
    DB::table('users')->whereJsonLength('roles', '>', 2)->get();
}

Type guard

function grammarSupportsJsonLength(): bool {
    $grammar = DB::connection()->getQueryGrammar();
    $method = new ReflectionMethod($grammar, 'compileJsonLength');
    return $method->getDeclaringClass()->getName() !== 'Illuminate\\Database\\Query\\Grammars\\Grammar';
}

Try / catch

try {
    DB::table('users')->whereJsonLength('roles', '>', 2)->get();
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'JSON length')) {
        DB::table('users')->whereRaw('json_array_length(roles) > ?', [2])->get();
    } else {
        throw $e;
    }
}

Prevention

Use a built-in connection — all four override compileJsonLength
If using a custom grammar, override compileJsonLength before calling whereJsonLength
Keep a raw json_array_length equivalent ready for custom drivers

When it happens

Trigger: Using whereJsonLength() on a query builder whose grammar is a custom class extending Grammar without implementing compileJsonLength. This occurs with third-party database drivers.

Common situations: Using a community database package that extends the base Grammar but has not implemented JSON length operations. Rare in practice since the four built-in engines all support it.

Related errors

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/5429a636aae6c906. Report an issue: GitHub.

Appendix: 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 e0f6eb3518)