laravel/framework · error · RuntimeException

This database engine does not support JSON contains operatio

Error message

This database engine does not support JSON contains operations.

What it means

The base Grammar::compileJsonContains() throws because this engine has no JSON_CONTAINS equivalent. All four standard grammars (SQLite, MySQL, Postgres, SQL Server) override compileJsonContains, so this base throw is reached only by a custom Grammar subclass that extends Illuminate\Database\Query\Grammars\Grammar directly without implementing JSON support.

Source

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

        return $not.$this->compileJsonContains(
            $where['column'],
            $this->parameter($where['value'])
        );
    }

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

    /**
     * Compile a "where JSON overlaps" clause.
     *
     * @param  \Illuminate\Database\Query\Builder  $query
     * @param  array  $where
     * @return string
     */
    protected function whereJsonOverlaps(Builder $query, $where)
    {
        $not = $where['not'] ? 'not ' : '';

        return $not.$this->compileJsonOverlaps(
            $where['column'],
            $this->parameter($where['value'])
        );
    }

View on GitHub (pinned to bd6b5437e6)

Solutions

Implement compileJsonContains($column, $value) on your custom Grammar using the engine's native JSON containment function.
Switch to one of the bundled connections that already supports JSON contains.
Avoid whereJsonContains and use a raw whereRaw with the engine's native JSON function.

Example fix

// before (custom grammar missing impl)
class MyGrammar extends Grammar {}
// calling $q->whereJsonContains('meta->tags', 'php');

// after
protected function compileJsonContains($column, $value)
{
    return "json_contains({$column}, {$value})";
}

Defensive patterns

Strategy: validation

Validate before calling

// Only safe on bundled grammars that override compileJsonContains
$driver = $query->getConnection()->getDriverName();
if (! in_array($driver, ['mysql','sqlite','pgsql','sqlsrv'])) {
    throw new \LogicException('whereJsonContains is not supported by this engine.');
}
$query->whereJsonContains('meta->tags', 'php');

Type guard

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

Prevention

Ensure custom grammars implement the full JSON where-clause family.
Add a capability test that exercises JSON methods against any new driver.
Prefer a bundled connection for JSON-heavy code.

When it happens

Trigger: Calling whereJsonContains($column, $value) while the connection uses a custom grammar that does not override compileJsonContains(). None of the four bundled grammars (sqlite/mysql/pgsql/sqlsrv) reach this base method.

Common situations: Registering a third-party or custom DB driver/grammar that extends the base Grammar without JSON methods. Forking an engine integration that has not yet implemented the JSON where-clause methods.

Related errors

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