laravel/framework · error · RuntimeException

This database engine does not support JSON contains key…

Error message

This database engine does not support JSON contains key operations.

What it means

The base Grammar's compileJsonContainsKey throws by default. All four major engine grammars (MySQL, PostgreSQL, SQLite, SQL Server) override it with engine-specific JSON path/exists functions. This error fires only for a custom grammar extending the base Grammar without an override, or a custom driver that lacks JSON key containment support.

Solutions

Switch to a built-in connection (mysql, pgsql, sqlite, or sqlsrv) — all four override compileJsonContainsKey
Override compileJsonContainsKey in your custom grammar class with the correct SQL for your engine
Replace whereJsonContainsKey with a raw clause using your engine's native JSON path/existence function

Example fix

// before — custom grammar without JSON key support
DB::table('users')->whereJsonContainsKey('metadata->theme')->get();

// after — raw clause for a custom engine
DB::table('users')->whereRaw("json_extract(metadata, '$.theme') IS NOT NULL")->get();

Defensive patterns

Strategy: try-catch

Validate before calling

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

if ($method->getDeclaringClass()->getName() !== 'Illuminate\\Database\\Query\\Grammars\\Grammar') {
    DB::table('users')->whereJsonContainsKey('metadata->theme')->get();
}

Type guard

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

Try / catch

try {
    DB::table('users')->whereJsonContainsKey('metadata->theme')->get();
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'JSON contains key')) {
        DB::table('users')->whereRaw("json_extract(metadata, '$.theme') IS NOT NULL")->get();
    } else {
        throw $e;
    }
}

Prevention

Use a built-in connection — all four override compileJsonContainsKey
If using a custom grammar, override compileJsonContainsKey before calling whereJsonContainsKey
Keep a raw json_extract / json_path equivalent ready for custom drivers

When it happens

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

Common situations: Using a community database package (e.g., a ClickHouse, DynamoDB, or Trino driver) that extends the base Grammar but has not implemented JSON contains-key operations.

Related errors

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

Appendix: source

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

    {
        $not = $where['not'] ? 'not ' : '';

        return $not.$this->compileJsonContainsKey(
            $where['column']
        );
    }

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

    /**
     * Compile a "where JSON length" clause.
     *
     * @param  \Illuminate\Database\Query\Builder  $query
     * @param  array  $where
     * @return string
     */
    protected function whereJsonLength(Builder $query, $where)
    {
        return $this->compileJsonLength(
            $where['column'],
            $where['operator'],
            $this->parameter($where['value'])
        );
    }

View on GitHub (pinned to e0f6eb3518)