Automattic/mongoose · error · ObjectParameterError

Parameter "doc" to init() must be an object, got "${doc}" (t

Error message

Parameter "doc" to init() must be an object, got "${doc}" (type ${typeof doc})

What it means

Document#init() hydrates a document from a raw MongoDB doc and requires that doc to be present. Passing null or undefined throws ObjectParameterError immediately; init() also accepts an optional callback, but a missing doc is always fatal.

Source

Thrown at lib/document.js:663

 * Note that `init` hooks are [synchronous](https://mongoosejs.com/docs/middleware.html#synchronous).
 *
 * @param {object} doc raw document returned by mongo
 * @param {object} [opts]
 * @param {boolean} [opts.hydratedPopulatedDocs=false] If true, hydrate and mark as populated any paths that are populated in the raw document
 * @param {Function} [fn]
 * @api public
 * @memberOf Document
 * @instance
 */

Document.prototype.init = function(doc, opts, fn) {
  if (typeof opts === 'function') {
    fn = opts;
    opts = null;
  }

  if (doc == null) {
    throw new ObjectParameterError(doc, 'doc', 'init');
  }

  this.$__init(doc, opts);

  if (fn) {
    fn(null, this);
  }

  return this;
};

/**
 * Alias for [`.init`](https://mongoosejs.com/docs/api/document.html#Document.prototype.init())
 *
 * @api public
 */

Document.prototype.$init = function() {

View on GitHub (pinned to 49cdab0136)

Solutions

Null-check before hydrating: if (raw) model.init(raw)
Handle the 'not found' case explicitly instead of forwarding null into init()

Example fix

// before
model.init(cache.get(id)); // null on cache miss → throws

// after
const raw = cache.get(id);
if (raw != null) model.init(raw);

Defensive patterns

Strategy: validation

Validate before calling

function hydrate(model, raw) {
  if (raw == null) throw new Error('cannot init: raw doc is missing');
  return model.init(raw);
}

Type guard

const hasRawDoc = (v) => v != null && typeof v === 'object';

Try / catch

try {
  model.init(raw);
} catch (err) {
  if (err.name === 'ObjectParameterError') {
    // source produced null (cache miss / not found) — handle explicitly
    return loadFromDatabase();
  }
  throw err;
}

Prevention

Check for null before hydrating from caches, queues, or query results
Treat a missing raw doc as a distinct code path (miss/not-found), never an init() argument
Wrap hydration of external data with validation that rejects null early

When it happens

Trigger: model.init(null), doc.init(undefined), or doc.init(cached) where cached is null after a cache miss; hydrating with a findOne() result without checking it first.

Common situations: Manual hydration from caches or message queues where entries can be missing; custom loaders or hooks that call init() on possibly-absent records.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

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