laravel/framework · error · RuntimeException

This database engine does not support JSON contains…

Error message

This database engine does not support JSON contains operations.

What it means

The base Grammar's compileJsonContains throws by default. All four major engine grammars (MySqlGrammar, PostgresGrammar, SQLiteGrammar, SqlServerGrammar) override it with engine-specific JSON_CONTAINS / jsonb @> / JSON functions. This error only fires for a custom grammar that extends the base Grammar directly without overriding the method.

Solutions

  1. Switch to a built-in connection (mysql, pgsql, sqlite, or sqlsrv) — all four override compileJsonContains
  2. If using a custom grammar, override compileJsonContains in your grammar class to emit the correct SQL for your engine
  3. Replace whereJsonContains with a raw clause that uses your engine's native JSON function

Example fix

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

// after — raw clause for a JSON-capable custom engine
DB::table('users')->whereRaw("json_contains(roles, '\"admin\"')")->get();
Defensive patterns

Strategy: try-catch

Validate before calling

if (method_exists(DB::connection()->getQueryGrammar(), 'compileJsonContains')) {
    $reflection = new ReflectionMethod(DB::connection()->getQueryGrammar(), 'compileJsonContains');
    if ($reflection->getDeclaringClass()->getName() !== 'Illuminate\\Database\\Query\\Grammars\\Grammar') {
        DB::table('users')->whereJsonContains('roles', 'admin')->get();
    }
}

Type guard

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

Try / catch

try {
    DB::table('users')->whereJsonContains('roles', 'admin')->get();
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'JSON contains')) {
        // fallback: raw JSON function or denormalized column
        DB::table('users')->whereRaw("roles LIKE '%admin%'")->get();
    } else {
        throw $e;
    }
}

Prevention

When it happens

Trigger: Using whereJsonContains() on a query builder whose grammar is a custom class extending Illuminate\Database\Query\Grammars\Grammar without implementing compileJsonContains. This would occur with a third-party or community database driver that does not yet support JSON operations.

Common situations: Integrating a community database package (e.g., a ClickHouse or Trino driver) that extends the base Grammar but has not implemented JSON contains. Using an outdated version of a driver package that predates JSON support.

Related errors

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

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