{"id":"79542b2e4258fc03","repo":"knex/knex","slug":"json-superset-where-clause-not-actually-supported-79542b","errorCode":null,"errorMessage":"Json superset where clause not actually supported by SQLite","messagePattern":"Json superset where clause not actually supported by SQLite","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/dialects/sqlite3/query/sqlite-querycompiler.js","lineNumber":322,"sourceCode":"      this.builder,\n      this.client,\n      this.bindingsHolder\n    )},${this.client.parameter(\n      params.path,\n      this.builder,\n      this.bindingsHolder\n    )})`;\n    return params.alias\n      ? this.client.alias(jsonCol, this.formatter.wrap(params.alias))\n      : jsonCol;\n  }\n\n  whereJsonPath(statement) {\n    return this._whereJsonPath('json_extract', statement);\n  }\n\n  whereJsonSupersetOf(statement) {\n    throw new Error(\n      'Json superset where clause not actually supported by SQLite'\n    );\n  }\n\n  whereJsonSubsetOf(statement) {\n    throw new Error(\n      'Json subset where clause not actually supported by SQLite'\n    );\n  }\n\n  onJsonPathEquals(clause) {\n    return this._onJsonPathEquals('json_extract', clause);\n  }\n\n  whereILike(statement) {\n    return `${this._columnClause(statement)} ${this._not(\n      statement,\n      'like '","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/knex/knex/blob/e25d54bcb707714a17f5a5744eba5c4246bb4d1d/lib/dialects/sqlite3/query/sqlite-querycompiler.js#L304-L340","documentation":"knex exposes a cross-dialect whereJsonSupersetOf builder for comparing JSON containment, but SQLite lacks a native 'JSON superset' operator comparable to PostgreSQL's @>. Rather than silently producing incorrect SQL, the SQLite query compiler throws this error the moment the builder is compiled. There is no partial support: the operation is simply unavailable on this dialect.","triggerScenarios":"Calling .whereJsonSupersetOf('col', value) on a knex instance configured with client: 'sqlite3'. Triggered at query-compilation time (when the query executes or .toSQL() is called).","commonSituations":"Sharing query code across PostgreSQL and SQLite (e.g. tests use SQLite, prod uses Postgres). JSON-column filtering logic ported from Postgres to SQLite.","solutions":["Replace whereJsonSupersetOf with a SQLite-compatible alternative: use json_extract() with explicit field comparisons via whereRaw or the json* builder helpers.","Run JSON-superset checks in application code after fetching rows.","Switch the test/dev database to PostgreSQL to match production if this query shape is required."],"exampleFix":"// before\nawait knex('t').whereJsonSupersetOf('meta', { active: true });\n// after\nawait knex('t').whereRaw(\"json_extract(meta, '$.active') = ?\", [1]);","handlingStrategy":"validation","validationCode":"function dialectSupportsJsonSuperset(client) {\n  return client && !/sqlite/i.test(client.dialect || '');\n}\nif (!dialectSupportsJsonSuperset(knex.client)) {\n  // use json_extract-based whereRaw instead of whereJsonSupersetOf\n}","typeGuard":"function supportsJsonSuperset(knex) {\n  return !/sqlite/i.test(knex.client.dialect || '');\n}","tryCatchPattern":"try {\n  await knex('t').whereJsonSupersetOf('meta', val);\n} catch (e) {\n  if (/Json superset where clause not actually supported/i.test(e.message)) {\n    // fall back to json_extract-based predicate\n  } else throw e;\n}","preventionTips":["Branch JSON-containment queries on dialect.","Centralize JSON query helpers with dialect-aware implementations.","Run integration tests against every supported dialect."],"tags":["sqlite","json","query-builder","dialect-unsupported"],"analyzedSha":"e25d54bcb707714a17f5a5744eba5c4246bb4d1d","analyzedAt":"2026-08-03T18:35:32.148Z","schemaVersion":2}