{"record":{"id":"9dcfc48db9e81a9f","repo":"Automattic/mongoose","slug":"aggregate-near-must-be-called-with-non-nullish","errorCode":null,"errorMessage":"Aggregate `near()` must be called with non-nullish argument","messagePattern":"Aggregate `near\\(\\)` must be called with non-nullish argument","errorType":"exception","errorClass":"MongooseError","httpStatus":null,"severity":"warning","filePath":"lib/aggregate.js","lineNumber":410,"sourceCode":" *       maxDistance: 0.008,\n *       query: { type: \"public\" },\n *       includeLocs: \"dist.location\",\n *       spherical: true,\n *     });\n *\n * @see $geoNear https://www.mongodb.com/docs/manual/reference/aggregation/geoNear/\n * @method near\n * @memberOf Aggregate\n * @instance\n * @param {object} arg\n * @param {object|number[]} arg.near GeoJSON point or coordinates array\n * @return {Aggregate}\n * @api public\n */\n\nAggregate.prototype.near = function(arg) {\n  if (arg == null) {\n    throw new MongooseError('Aggregate `near()` must be called with non-nullish argument');\n  }\n  if (arg.near == null) {\n    throw new MongooseError('Aggregate `near()` argument must have a `near` property');\n  }\n  const coordinates = Array.isArray(arg.near) ? arg.near : arg.near.coordinates;\n  if (typeof arg.near === 'object' && (!Array.isArray(coordinates) || coordinates.length < 2 || coordinates.find(c => typeof c !== 'number'))) {\n    throw new MongooseError(`Aggregate \\`near()\\` argument has invalid coordinates, got \"${coordinates}\"`);\n  }\n\n  const op = {};\n  op.$geoNear = arg;\n  return this.append(op);\n};\n\n/*!\n * define methods\n */\n","sourceCodeStart":392,"sourceCodeEnd":428,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/aggregate.js#L392-L428","documentation":"When a schema path is added, Mongoose checks whether the FIRST segment of the dotted path collides with a reserved name on the Document prototype (save, errors, schema, on, once, emit, get, set, init, isNew, toObject, toJSON, ...). Because these become properties/methods on every document, a user path with the same name shadows them and can break Mongoose internals. Since Mongoose 5 this is only a warning (utils.warn), not an exception; special properties like $.foo still throw, but reserved names just warn unless suppressed.","triggerScenarios":"Defining new Schema({ errors: String }), { save: Boolean }, { on: Date }, { schema: Mixed }, or a nested first segment like 'init.name' in the schema definition; also indirect definitions via schema.add({ ... }) or a nested path whose first piece is reserved.","commonSituations":"Logging/event schemas that naturally want a field named 'on' or 'init'; audit schemas with an 'errors' array; migrating a MongoDB collection whose documents contain keys that collide with Document methods; ORM-agnostic code reused across libraries where the same field name is fine elsewhere.","solutions":["Rename the path to something non-reserved, e.g. 'save' -> 'isSaved', 'on' -> 'activeAt', 'errors' -> 'validationIssues' (you can keep the MongoDB key different using the 'alias' option or a virtual).","If the collision is intentional and tested, silence it per schema: new Schema({...}, { suppressReservedKeysWarning: true }).","Use field aliases to keep the stored key: { errors: { type: String, alias: 'docErrors' } } and access doc.docErrors.","Audit usages of doc.toObject()/JSON serialization after renaming to make sure API consumers are updated."],"exampleFix":"// before\nconst schema = new Schema({ on: Date, errors: [String] }); // warns\n\n// after\nconst schema = new Schema({\n  activeAt: { type: Date, alias: 'on' },\n  issues: { type: [String], alias: 'errors' }\n});","handlingStrategy":"validation","validationCode":"const RESERVED = new Set(['save','errors','schema','on','once','emit','init','get','set','isNew','toObject','toJSON','populate','remove','deleteOne','updateOne','overwrite','collection','db','model','$__']);\nfunction assertSafePaths(definition) {\n  for (const key of Object.keys(definition)) {\n    if (RESERVED.has(key.split('.')[0])) {\n      throw new Error(`Field \"${key}\" collides with a reserved Document name; rename it or use suppressReservedKeysWarning`);\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run a schema-definition lint step in CI that flags reserved first-segment path names.","Prefer aliases for API compatibility instead of storing reserved keys.","Review the reserved list in the Mongoose docs when adding fields to shared/base schemas."],"tags":["mongoose","schema","reserved-name","warning","naming"],"backgroundTag":"reserved-keyword-conflict","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}