laravel/framework · error · RuntimeException

This database engine does not support JSON contains key oper

Error message

This database engine does not support JSON contains key operations.

What it means

The base Grammar::compileJsonContainsKey() throws because this engine has no JSON key-existence predicate. All four bundled grammars (SQLite, MySQL, Postgres, SQL Server) override compileJsonContainsKey, so this base throw is only reached by a custom Grammar subclass that extends the base Grammar without the JSON key method.

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 bd6b5437e6)

Solutions

Implement compileJsonContainsKey($column) on the custom Grammar with the engine's native JSON key-existence function.
Use one of the bundled drivers that supports the operation.
Replace whereJsonContainsKey with a whereRaw using the native JSON path/exists function.

Example fix

// before (custom grammar)
$q->whereJsonContainsKey('meta->enabled');
// throws base Grammar::compileJsonContainsKey

// after
protected function compileJsonContainsKey($column)
{
    return "json_exists({$column})";
}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

Complete the JSON method set when writing a custom grammar.
Use bundled drivers for JSON key-existence checks.
Add capability tests for any new driver integration.

When it happens

Trigger: Calling whereJsonContainsKey($column) on a connection whose grammar does not override compileJsonContainsKey (i.e. a custom/third-party grammar). No bundled engine reaches this base method.

Common situations: Writing/testing a new database driver integration that extends Grammar but has not implemented the JSON key methods yet. Using a community package providing a grammar that is incomplete.

Related errors

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