Automattic/mongoose · error · InvalidSchemaOptionError

Cannot create use schema for property "${key}" because the s

Error message

Cannot create use schema for property "${key}" because the schema has the timeseries option enabled.

What it means

InvalidSchemaOptionError thrown when a DocumentArray (embedded subdocument array) is created from a schema carrying `{ timeseries: true }`. Timeseries is a collection-level MongoDB option that changes how the whole collection stores data; an embedded array lives inside parent documents and cannot be a timeseries, so Mongoose rejects the combination at schema-construction time instead of silently ignoring it.

Source

Thrown at lib/schema/documentArray.js:44

let MongooseDocumentArray;
let Subdocument;

/**
 * SubdocsArray SchemaType constructor
 *
 * @param {string} key
 * @param {Schema} schema
 * @param {object} options
 * @param {object} schemaOptions
 * @param {Schema} parentSchema
 * @inherits SchemaArray
 * @api public
 */

function SchemaDocumentArray(key, schema, options, schemaOptions, parentSchema) {
  if (schema.options?.timeseries) {
    throw new InvalidSchemaOptionError(key, 'timeseries');
  }
  const schemaTypeIdOption = SchemaDocumentArray.defaultOptions?._id;
  if (schemaTypeIdOption != null) {
    schemaOptions = schemaOptions || {};
    schemaOptions._id = schemaTypeIdOption;
  }

  if (schemaOptions?._id != null) {
    schema = handleIdOption(schema, schemaOptions);
  } else if (options?._id != null) {
    schema = handleIdOption(schema, options);
  }

  const Constructor = _createConstructor(schema, options);
  Constructor.prototype.$basePath = key;
  Constructor.path = key;

  const $parentSchemaType = this;

View on GitHub (pinned to 49cdab0136)

Solutions

1. Remove `timeseries: true` from the embedded schema — it only belongs on the top-level model's schema/collection options
2. If you need real time-series storage, keep it as a separate model on its own collection and reference it by ObjectId from the parent
3. If the option leaked in through a shared schema module, clone the schema and delete `schema.options.timeseries` before embedding
4. Add a unit test asserting your compiled schemas construct, so invalid options fail in CI, not at runtime

Example fix

// before
const readingSchema = new Schema({ t: Date, v: Number }, { timeseries: true });
new Schema({ readings: [readingSchema] });

// after
const readingSchema = new Schema({ t: Date, v: Number });
new Schema({ readings: [readingSchema] });
// and, if needed, a separate timeseries model:
// db.model('Reading', readingSchema, 'readings'); + createCollection({ timeseries: ... })

function assertEmbeddable(subSchema, key) {
  if (subSchema.options && subSchema.options.timeseries) {
    throw new Error(`cannot embed schema ${key}: timeseries option must be removed`);
  }
}
assertEmbeddable(readingSchema, 'readings');
new Schema({ readings: [readingSchema] });

try { new Schema({ readings: [readingSchema] }); } catch (err) { if (err.name === 'InvalidSchemaOptionError' || /timeseries/.test(err.message)) { delete readingSchema.options.timeseries; } else throw err; }

When it happens

Trigger: `new Schema({ readings: [new Schema({ t: Date, v: Number }, { timeseries: true })] })` — any subdocument-array element schema with the timeseries option set. Also building a DocumentArray schematype directly with such a schema.

Common situations: Copying a working standalone timeseries model's schema into another schema as an embedded array during refactors; merging shared schema definitions where one variant was used for a timeseries collection; following a timeseries tutorial and pasting options into the wrong place.

Related errors

• Cannot create use schema for property "${path}" because the
• Aggregate `near()` must be called with non-nullish argument
• Invalid sort() argument. Must be a string or object.
• If thenExpr or elseExpr is string, it must be either $$DESCE
• Field `${path}` is not in schema and strict mode is set to t

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