Automattic/mongoose · warning · TypeError

Invalid arg "${arg}" to sortByCount(), must be string or obj

Error message

Invalid arg "${arg}" to sortByCount(), must be string or object

What it means

This module-level warning prints once when Mongoose is first required inside a Jest run that uses the default jsdom test environment. jsdom provides a browser-like global `window`, under which the MongoDB driver behaves differently (and historically failed on missing Node APIs), so Mongoose nudges you to run Node-style tests in the node environment. It is purely informational — gated on typeof jest !== 'undefined' && typeof window !== 'undefined' — and is hidden by SUPPRESS_JEST_WARNINGS.

Source

Thrown at lib/aggregate.js:553

 *
 *     aggregate.sortByCount('users');
 *     aggregate.sortByCount({ $mergeObjects: [ "$employee", "$business" ] })
 *
 * @see $sortByCount https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortByCount/
 * @param {object|string} arg
 * @return {Aggregate} this
 * @api public
 */

Aggregate.prototype.sortByCount = function(arg) {
  if (arg && typeof arg === 'object') {
    return this.append({ $sortByCount: arg });
  } else if (typeof arg === 'string') {
    return this.append({
      $sortByCount: (arg[0] === '$') ? arg : '$' + arg
    });
  } else {
    throw new TypeError('Invalid arg "' + arg + '" to sortByCount(), ' +
      'must be string or object');
  }
};

/**
 * Appends new custom $lookup operator to this aggregate pipeline.
 *
 * #### Example:
 *
 *     aggregate.lookup({ from: 'users', localField: 'userId', foreignField: '_id', as: 'users' });
 *
 * @see $lookup https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#pipe._S_lookup
 * @param {object} options to $lookup as described in the above link
 * @return {Aggregate}
 * @api public
 */

Aggregate.prototype.lookup = function(options) {

View on GitHub (pinned to 49cdab0136)

Solutions

1. Set the Node environment for backend tests: in jest.config.js use testEnvironment: 'node'.
2. Per-file override when a mixed suite exists: add the docblock /** @jest-environment node */ at the top of the DB test file.
3. If some tests genuinely need jsdom, split projects with Jest's projects option: one node project for DB tests, one jsdom for UI.
4. As a last resort set SUPPRESS_JEST_WARNINGS=true in the env — but fixing the environment is the real fix.

Example fix

// before (jest.config.js)
module.exports = { testEnvironment: 'jsdom' };

// after
module.exports = { testEnvironment: 'node' };

// or per file, first line of test:
/** @jest-environment node */

// jest.config.js — fail fast on wrong environment for DB suites
module.exports = {
  projects: [
    { displayName: 'unit', testEnvironment: 'jsdom', testMatch: ['<rootDir>/src/**/*.test.js'] },
    { displayName: 'api', testEnvironment: 'node', testMatch: ['<rootDir>/test/**/*.test.js'] }
  ]
};

When it happens

Trigger: Requiring mongoose in any test file while Jest's testEnvironment is 'jsdom' (the default in jest-environment-jsdom setups and in older Jest versions); integration tests that spin up a real connection inside component tests configured for the browser environment.

Common situations: Frontend repos that added API tests without changing jest.config; Create React App / Next.js default configs that use jsdom for everything; CI logs polluted by the warning after adding a database test suite; upgrading Jest where jsdom stopped being the bundled default and configs were pinned to it.

Related errors

• Invalid graphLookup() argument. Must be an object.
• Aggregate `near()` must be called with non-nullish argument
• Invalid arg "${arg}" to unwind(), must be string or object
• Invalid sort() argument. Must be a string or object.
• If thenExpr or elseExpr is string, it must be either $$DESCE

AI-assisted analysis of Automattic/mongoose@49cdab0136 (2026-08-21). Data as JSON: /api/errors/7bb87517a9c18dc0. Report an issue: GitHub.