Automattic/mongoose · error · MongooseError

Cannot set special property `${sub}` on a schema

Error message

Cannot set special property `${sub}` on a schema

What it means

Error "Cannot set special property `${sub}` on a schema" thrown in Automattic/mongoose.

Source

Thrown at lib/schema.js:1329

  if (Object.hasOwn(reserved, firstPieceOfPath) && !this.options.suppressReservedKeysWarning) {
    const errorMessage = `\`${firstPieceOfPath}\` is a reserved schema pathname and may break some functionality. ` +
      'You are allowed to use it, but use at your own risk. ' +
      'To disable this warning pass `suppressReservedKeysWarning` as a schema option.';

    utils.warn(errorMessage);
  }

  if (typeof obj === 'object' && utils.hasUserDefinedProperty(obj, 'ref')) {
    validateRef(obj.ref, path);
  }

  // update the tree
  let branch = this.tree;
  let fullPath = '';

  for (const sub of subpaths) {
    if (utils.specialProperties.has(sub)) {
      throw new MongooseError('Cannot set special property `' + sub + '` on a schema');
    }
    fullPath = fullPath += (fullPath.length > 0 ? '.' : '') + sub;
    if (!branch[sub]) {
      this.nested[fullPath] = true;
      branch[sub] = {};
    }
    if (typeof branch[sub] !== 'object') {
      const msg = 'Cannot set nested path `' + path + '`. '
          + 'Parent path `'
          + fullPath
          + '` already set to type ' + branch[sub].name
          + '.';
      throw new MongooseError(msg);
    }
    branch = branch[sub];
  }

  branch[last] = clone(obj);

View on GitHub (pinned to 49cdab0136)

When it happens

Trigger: Thrown at lib/schema.js:1329 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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