Automattic/mongoose · error · MongooseError

Cannot create DocumentArrayElement schematype without a pare

Error message

Cannot create DocumentArrayElement schematype without a parent

What it means

Internal invariant error: SchemaDocumentArrayElement (the schematype Mongoose auto-creates for paths inside an array element, e.g. `arr.name`) requires `options.$parentSchemaType` — a back-reference to the owning SchemaDocumentArray — and its constructor throws immediately when it is missing. You should never see this from normal model code; it means some code path is constructing or copying element schematypes without the internal wiring Mongoose sets up itself.

Source

Thrown at lib/schema/documentArrayElement.js:30

/**
 * DocumentArrayElement SchemaType constructor. Mongoose calls this internally when you define a new document array in your schema.
 *
 * #### Example:
 *     const schema = new Schema({ users: [{ name: String }] });
 *     schema.path('users.$'); // SchemaDocumentArrayElement with schema `new Schema({ name: String })`
 *
 * @param {string} path
 * @param {Schema} schema
 * @param {object} options
 * @param {Schema} parentSchema
 * @inherits SchemaType
 * @api public
 */

function SchemaDocumentArrayElement(path, schema, options, parentSchema) {
  this.$parentSchemaType = options?.$parentSchemaType;
  if (!this.$parentSchemaType) {
    throw new MongooseError('Cannot create DocumentArrayElement schematype without a parent');
  }
  delete options.$parentSchemaType;

  SchemaType.call(this, path, options, 'DocumentArrayElement', parentSchema);

  this.$isMongooseDocumentArrayElement = true;
  this.Constructor = options?.Constructor;
  this.schema = schema;
}

/**
 * This schema type's name, to defend against minifiers that mangle
 * function names.
 *
 * @api public
 */
SchemaDocumentArrayElement.schemaName = 'DocumentArrayElement';

View on GitHub (pinned to 49cdab0136)

Solutions

1. Never construct DocumentArrayElement yourself — declare `arr: [subSchema]` and let Mongoose build element types
2. Update or replace plugins that manipulate `schema.paths`/`schema.nested` internals; check their Mongoose version support
3. If you genuinely must build one, pass the owning array schematype: `opts.$parentSchemaType = mySchemaDocumentArrayInstance`
4. Pin/upgrade Mongoose and plugins together and re-run your test suite — this error is a compatibility smell

Example fix

// before
const el = new mongoose.Schema.Types.DocumentArrayElement('name', sub, {}); // throws

// after
const parent = new Schema({ items: [sub] }); // let Mongoose create element paths
// access via parent.path('items').schema.path('name') if needed

// guard your schema-manipulation utilities:
function assertNoRawElementTypes(schema) {
  for (const [path, type] of Object.entries(schema.paths)) {
    if (type.$isMongooseDocumentArrayElement && !type.$parentSchemaType) {
      throw new Error(`plugin must not re-register ${path} without $parentSchemaType`);
    }
  }
}

try { buildSchemaViaPlugin(parts); } catch (err) { if (/DocumentArrayElement schematype without a parent/.test(err.message)) { throw new Error('schema plugin incompatible with this mongoose version — update it'); } throw err; }

When it happens

Trigger: Directly doing `new mongoose.Schema.Types.DocumentArrayElement(path, subSchema, opts)` without `$parentSchemaType`; plugins or utilities that traverse `schema.paths` and rebuild/re-register paths (deep-clone of schemas, schema merging libraries) and drop the `$parentSchemaType` option; copying a DocumentArrayElement path into another schema via `add()`.

Common situations: Schema-merging/normalizing plugins (e.g. mongoose-merge-plugin style) written against older Mongoose internals after a Mongoose upgrade; utility code that deep-clones schema definitions; mixing Mongoose major versions with stale compiled plugins.

Related errors

• Invalid project() argument. Must be string or object
• Base SchemaType class does not implement a `cast()` function
• Arguments must be aggregate pipeline operators
• Invalid addFields() argument. Must be an object
• Aggregate `near()` must be called with non-nullish argument

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