{"record":{"id":"fd12a87354ae757c","repo":"laravel/framework","slug":"this-database-engine-does-not-support-json-contain-fd12a8","errorCode":null,"errorMessage":"This database engine does not support JSON contains key operations.","messagePattern":"This database engine does not support JSON contains key operations\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Query/Grammars/Grammar.php","lineNumber":781,"sourceCode":"    {\n        $not = $where['not'] ? 'not ' : '';\n\n        return $not.$this->compileJsonContainsKey(\n            $where['column']\n        );\n    }\n\n    /**\n     * Compile a \"JSON contains key\" statement into SQL.\n     *\n     * @param  string  $column\n     * @return string\n     *\n     * @throws \\RuntimeException\n     */\n    protected function compileJsonContainsKey($column)\n    {\n        throw new RuntimeException('This database engine does not support JSON contains key operations.');\n    }\n\n    /**\n     * Compile a \"where JSON length\" clause.\n     *\n     * @param  \\Illuminate\\Database\\Query\\Builder  $query\n     * @param  array  $where\n     * @return string\n     */\n    protected function whereJsonLength(Builder $query, $where)\n    {\n        return $this->compileJsonLength(\n            $where['column'],\n            $where['operator'],\n            $this->parameter($where['value'])\n        );\n    }\n","sourceCodeStart":763,"sourceCodeEnd":799,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Query/Grammars/Grammar.php#L763-L799","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before — custom grammar without JSON key support\nDB::table('users')->whereJsonContainsKey('metadata->theme')->get();\n\n// after — raw clause for a custom engine\nDB::table('users')->whereRaw(\"json_extract(metadata, '$.theme') IS NOT NULL\")->get();","handlingStrategy":"try-catch","validationCode":"$grammar = DB::connection()->getQueryGrammar();\n$method = new ReflectionMethod($grammar, 'compileJsonContainsKey');\n\nif ($method->getDeclaringClass()->getName() !== 'Illuminate\\\\Database\\\\Query\\\\Grammars\\\\Grammar') {\n    DB::table('users')->whereJsonContainsKey('metadata->theme')->get();\n}","typeGuard":"function grammarSupportsJsonContainsKey(): bool {\n    $grammar = DB::connection()->getQueryGrammar();\n    $method = new ReflectionMethod($grammar, 'compileJsonContainsKey');\n    return $method->getDeclaringClass()->getName() !== 'Illuminate\\\\Database\\\\Query\\\\Grammars\\\\Grammar';\n}","tryCatchPattern":"try {\n    DB::table('users')->whereJsonContainsKey('metadata->theme')->get();\n} catch (\\RuntimeException $e) {\n    if (str_contains($e->getMessage(), 'JSON contains key')) {\n        DB::table('users')->whereRaw(\"json_extract(metadata, '$.theme') IS NOT NULL\")->get();\n    } else {\n        throw $e;\n    }\n}","preventionTips":["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"],"tags":["json","grammar","database","custom-driver"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}