laravel/framework · error · RuntimeException

This database engine does not support JSON overlaps operatio

Error message

This database engine does not support JSON overlaps operations.

What it means

The base Grammar::compileJsonOverlaps() throws because this engine has no JSON array-overlap predicate. Only MySqlGrammar (and MariaDbGrammar inheriting it) overrides compileJsonOverlaps; SQLite, Postgres, and SQL Server all fall through to the base method and throw.

Source

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

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

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

    /**
     * Prepare the binding for a "JSON contains" statement.
     *
     * @param  mixed  $binding
     * @return string
     */
    public function prepareBindingForJsonContains($binding)
    {
        return json_encode($binding, JSON_UNESCAPED_UNICODE);
    }

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

View on GitHub (pinned to bd6b5437e6)

Solutions

On Postgres use jsonb && (overlap) via whereRaw: whereRaw('meta->\'tags\' ?| ?', [...]).
On SQLite use a JSON_EACH/EXISTS subquery via whereRaw to test overlap.
Restrict whereJsonOverlaps usage to MySQL/MariaDB, or normalize the tag array into a related table for portable queries.

Example fix

// before
$query->whereJsonOverlaps('meta->tags', $tags);

// after (Postgres portable)
if ($query->getConnection()->getDriverName() === 'pgsql') {
    $query->whereRaw('jsonb_exists_any((meta->\'tags\')::jsonb, ?)', [$tags]);
} else {
    $query->whereJsonOverlaps('meta->tags', $tags);
}

Defensive patterns

Strategy: validation

Validate before calling

$driver = $query->getConnection()->getDriverName();
if ($driver === 'mysql') {
    $query->whereJsonOverlaps('meta->tags', $tags);
} else {
    // Postgres: jsonb_exists_any; SQLite: JSON_EACH subquery
    throw new \LogicException('whereJsonOverlaps requires MySQL/MariaDB.');
}

Type guard

function supportsJsonOverlaps(\Illuminate\Database\Connection $connection): bool
{
    return $connection instanceof \Illuminate\Database\MySqlConnection;
}

Prevention

Normalise tag arrays into a join table for portable overlap queries.
Keep whereJsonOverlaps behind a MySQL-only code path.
Document the MySQL-only nature in the query builder helper.

When it happens

Trigger: Calling whereJsonOverlaps($column, $value) (or orWhereJsonOverlaps / whereJsonDoesntOverlap) on a sqlite, pgsql, or sqlsrv connection.

Common situations: Storing tag arrays in a JSON column and filtering with whereJsonOverlaps, then running the same query on Postgres or SQLite. Sharing query-builder code between a MySQL production DB and a SQLite test DB.

Related errors

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