mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Document must be a valid JavaScript object

Error message

Document must be a valid JavaScript object

What it means

Thrown by makeUpdateStatement when the update/replacement document passed to update/updateOne/updateMany/replaceOne/findOneAnd* is null or not an object. The mutation argument must be a JavaScript object (or array pipeline for updates). A null/undefined/primitive triggers this MongoInvalidArgumentError before any wire request.

Source

Thrown at src/operations/update.ts:270

      upsertedId:
        Array.isArray(res.upserted) && res.upserted.length > 0 ? res.upserted[0]._id : null,
      upsertedCount: Array.isArray(res.upserted) && res.upserted.length ? res.upserted.length : 0,
      matchedCount: Array.isArray(res.upserted) && res.upserted.length > 0 ? 0 : res.n
    };
  }
}

export function makeUpdateStatement(
  filter: Document,
  update: Document | Document[],
  options: UpdateOptions & { multi?: boolean } & { sort?: Sort }
): UpdateStatement {
  if (filter == null || typeof filter !== 'object') {
    throw new MongoInvalidArgumentError('Selector must be a valid JavaScript object');
  }

  if (update == null || typeof update !== 'object') {
    throw new MongoInvalidArgumentError('Document must be a valid JavaScript object');
  }

  const op: UpdateStatement = { q: filter, u: update };
  if (typeof options.upsert === 'boolean') {
    op.upsert = options.upsert;
  }

  if (options.multi) {
    op.multi = options.multi;
  }

  if (options.hint) {
    op.hint = options.hint;
  }

  if (options.arrayFilters) {
    op.arrayFilters = options.arrayFilters;
  }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Ensure the update argument is always an object: default it, or skip the write entirely when there is nothing to update.
2. For updateOne/updateMany include atomic operators; for replaceOne include a plain document.
3. Add a guard that skips the call when the constructed update is null/undefined.
4. Check the return of helper functions that build update documents.

Example fix

// before
await collection.updateOne(filter, buildUpdate(data)); // buildUpdate returned undefined
// after
const update = buildUpdate(data);
if (update) await collection.updateOne(filter, update);

function isDocObject(d) {
  return d != null && typeof d === 'object';
}
if (!isDocObject(update)) throw new Error('update must be a non-null object');
await collection.updateOne(filter, update);

function isDocObject(d: unknown): d is Record<string, unknown> {
  return d != null && typeof d === 'object';
}

When it happens

Trigger: collection.updateOne(filter, null) or updateOne(filter, undefined) because the update was constructed conditionally and ended up unset; passing a primitive where the update document belongs; a function returning undefined used as the update argument.

Common situations: Conditionally built update objects where a branch returns nothing; bad destructuring; refactoring that moved update construction out of a helper which can now return undefined; passing the wrong variable.

Related errors

• Update document requires atomic operators
• Update document requires atomic operators
• Update document requires atomic operators
• Replacement document must not contain atomic operators
• Selector must be a valid JavaScript object

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/d5de58c55ba9e53a.json. Report an issue: GitHub.