knex/knex · error · Error

Json superset where clause not actually supported by SQLite

Error message

Json superset where clause not actually supported by SQLite

What it means

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.

Source

Thrown at lib/dialects/sqlite3/query/sqlite-querycompiler.js:322

      this.builder,
      this.client,
      this.bindingsHolder
    )},${this.client.parameter(
      params.path,
      this.builder,
      this.bindingsHolder
    )})`;
    return params.alias
      ? this.client.alias(jsonCol, this.formatter.wrap(params.alias))
      : jsonCol;
  }

  whereJsonPath(statement) {
    return this._whereJsonPath('json_extract', statement);
  }

  whereJsonSupersetOf(statement) {
    throw new Error(
      'Json superset where clause not actually supported by SQLite'
    );
  }

  whereJsonSubsetOf(statement) {
    throw new Error(
      'Json subset where clause not actually supported by SQLite'
    );
  }

  onJsonPathEquals(clause) {
    return this._onJsonPathEquals('json_extract', clause);
  }

  whereILike(statement) {
    return `${this._columnClause(statement)} ${this._not(
      statement,
      'like '

View on GitHub (pinned to e25d54bcb7)

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.

Example fix

// before
await knex('t').whereJsonSupersetOf('meta', { active: true });
// after
await knex('t').whereRaw("json_extract(meta, '$.active') = ?", [1]);

Defensive patterns

Strategy: validation

Validate before calling

function dialectSupportsJsonSuperset(client) {
  return client && !/sqlite/i.test(client.dialect || '');
}
if (!dialectSupportsJsonSuperset(knex.client)) {
  // use json_extract-based whereRaw instead of whereJsonSupersetOf
}

Type guard

function supportsJsonSuperset(knex) {
  return !/sqlite/i.test(knex.client.dialect || '');
}

Try / catch

try {
  await knex('t').whereJsonSupersetOf('meta', val);
} catch (e) {
  if (/Json superset where clause not actually supported/i.test(e.message)) {
    // fall back to json_extract-based predicate
  } else throw e;
}

Prevention

Branch JSON-containment queries on dialect.
Centralize JSON query helpers with dialect-aware implementations.
Run integration tests against every supported dialect.

When it happens

Trigger: 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).

Common situations: Sharing query code across PostgreSQL and SQLite (e.g. tests use SQLite, prod uses Postgres). JSON-column filtering logic ported from Postgres to SQLite.

Related errors

AI-assisted analysis of knex/knex@e25d54bcb7 (2026-08-03). Data as JSON: /data/errors/79542b2e4258fc03.json. Report an issue: GitHub.