Automattic/mongoose · warning · MongooseError

Aggregate `near()` argument has invalid coordinates, got "${

Error message

Aggregate `near()` argument has invalid coordinates, got "${coordinates}"

What it means

getChanges() on a document returns the pending changes formatted for MongoDB ($set/$unset/$inc etc.), but it uses an unprefixed name that can collide with user-defined schema methods or paths. Mongoose deprecated it in favor of the $-prefixed $getChanges(), which is reserved for internal-style APIs and can never collide. The warning prints on every call; the method still works and simply delegates to $getChanges().

Source

Thrown at lib/aggregate.js:417

 * @method near
 * @memberOf Aggregate
 * @instance
 * @param {object} arg
 * @param {object|number[]} arg.near GeoJSON point or coordinates array
 * @return {Aggregate}
 * @api public
 */

Aggregate.prototype.near = function(arg) {
  if (arg == null) {
    throw new MongooseError('Aggregate `near()` must be called with non-nullish argument');
  }
  if (arg.near == null) {
    throw new MongooseError('Aggregate `near()` argument must have a `near` property');
  }
  const coordinates = Array.isArray(arg.near) ? arg.near : arg.near.coordinates;
  if (typeof arg.near === 'object' && (!Array.isArray(coordinates) || coordinates.length < 2 || coordinates.find(c => typeof c !== 'number'))) {
    throw new MongooseError(`Aggregate \`near()\` argument has invalid coordinates, got "${coordinates}"`);
  }

  const op = {};
  op.$geoNear = arg;
  return this.append(op);
};

/*!
 * define methods
 */

'group match skip limit out densify fill'.split(' ').forEach(function($operator) {
  Aggregate.prototype[$operator] = function(arg) {
    const op = {};
    op['$' + $operator] = arg;
    return this.append(op);
  };
});

View on GitHub (pinned to 49cdab0136)

Solutions

1. Replace every doc.getChanges() call with doc.$getChanges() — identical return value, no warning.
2. If you also mutate anything from the result, remember it is a snapshot of the change set, not a live object.
3. For 'did this path change?' prefer doc.isModified(path) or doc.$getChanges().$set ?? {} instead of diffing the whole object.

Example fix

// before
const changes = doc.getChanges();

// after
const changes = doc.$getChanges();

When it happens

Trigger: Calling doc.getChanges() to inspect pending modifications before save, e.g. change-detection or audit-diff features; any helper that logs the delta produced by $__delta().

Common situations: Audit/diff utilities built on older Mongoose versions; code that shows users which fields changed; upgrading Mongoose and seeing the warning flood logs; frameworks that call getChanges() internally on every request.

Related errors

• Aggregate `near()` argument must have a `near` property
• Aggregate.prototype.explain() no longer accepts a callback
• Aggregate has empty pipeline
• Aggregate pipeline for $unionWith cannot include `$out` or `
• Parameter "obj" to Document() must be an object, got "${obj}

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