{"record":{"id":"dbf7303d3883422f","repo":"Automattic/mongoose","slug":"sort-options-argument-must-be-an-object-or-nulli","errorCode":null,"errorMessage":"sort() options argument must be an object or nullish","messagePattern":"sort\\(\\) options argument must be an object or nullish","errorType":"exception","errorClass":"MongooseError","httpStatus":null,"severity":"error","filePath":"lib/query.js","lineNumber":3140,"sourceCode":" *\n * #### Note:\n *\n * Cannot be used with `distinct()`\n *\n * @param {object|string|Array<Array<(string | number)>>} arg\n * @param {object} [options]\n * @param {boolean} [options.override=false] If true, replace existing sort options with `arg`\n * @return {Query} this\n * @see cursor.sort https://www.mongodb.com/docs/manual/reference/method/cursor.sort/\n * @api public\n */\n\nQuery.prototype.sort = function(arg, options) {\n  if (arguments.length > 2) {\n    throw new MongooseError('sort() takes at most 2 arguments');\n  }\n  if (options != null && typeof options !== 'object') {\n    throw new MongooseError('sort() options argument must be an object or nullish');\n  }\n\n  if (this.options.sort == null) {\n    this.options.sort = {};\n  }\n  if (options?.override) {\n    this.options.sort = {};\n  }\n  const sort = this.options.sort;\n  if (typeof arg === 'string') {\n    const properties = arg.indexOf(' ') === -1 ? [arg] : arg.split(' ');\n    for (let property of properties) {\n      const ascend = '-' == property[0] ? -1 : 1;\n      if (ascend === -1) {\n        property = property.slice(1);\n      }\n      if (specialProperties.has(property)) {\n        continue;","sourceCodeStart":3122,"sourceCodeEnd":3158,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/query.js#L3122-L3158","documentation":"The second argument to sort(), when present, must be an options object or nullish; its only documented key is override, which replaces the existing sort instead of merging. A primitive in that slot — .sort({ a: 1 }, true), .sort(spec, -1) — throws this MongooseError before any sort is applied.","triggerScenarios":".sort({ createdAt: -1 }, true) expecting the boolean to mean 'override'; .sort('a', 1) reusing the (field, direction) habit; passing a string flag as the second argument.","commonSituations":"Confusing the options slot with a direction argument; copying the (arg, options) shape but passing a feature-flag boolean; partial refactors from positional direction to options.","solutions":["Pass { override: true } when you want the new sort to replace the accumulated one","Otherwise omit the second argument or pass null"],"exampleFix":"// before\nq.sort({ createdAt: -1 }, true);\n\n// after\nq.sort({ createdAt: -1 }, { override: true });","handlingStrategy":"type-guard","validationCode":"const sortOpts = wantOverride === true ? { override: true } : undefined;\nq.sort(spec, sortOpts);","typeGuard":"const isSortOptions = (v) => v == null || (typeof v === 'object' && !Array.isArray(v));","tryCatchPattern":null,"preventionTips":["The only valid second argument to sort() is an options object like { override: true }","Never pass a boolean or number as the second argument","Encode direction inside the sort spec, not in extra arguments"],"tags":["mongoose","query","sort","options","invalid-argument"],"backgroundTag":"invalid-sort-argument","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}