Automattic/mongoose · error · InvalidSchemaOptionError

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

Error message

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

What it means

Timeseries collections are a collection-level MongoDB feature. Mongoose refuses to embed a schema declared with `{ timeseries: ... }` as a single nested subdocument and throws InvalidSchemaOptionError at schema build time (lib/schema/subdocument.js:41), because a time series cannot live inside another document.

Source

Thrown at lib/schema/subdocument.js:41

let SubdocumentType;

module.exports = SchemaSubdocument;

/**
 * Single nested subdocument SchemaType constructor.
 *
 * @param {Schema} schema
 * @param {string} path
 * @param {object} options
 * @param {Schema} parentSchema
 * @inherits SchemaType
 * @api public
 */

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

  schema = handleIdOption(schema, options);

  this.Constructor = _createConstructor(schema, null, options);
  this.Constructor.path = path;
  this.Constructor.prototype.$basePath = path;
  this.schema = schema;
  this.$isSingleNested = true;
  this.base = schema.base;
  SchemaType.call(this, path, options, 'Embedded', parentSchema);
}

View on GitHub (pinned to 49cdab0136)

Solutions

1. Remove the `timeseries` option from the embedded schema; declare the nested schema without it
2. Keep `timeseries` only on the top-level schema passed to `mongoose.model()`
3. If the series must scale independently, store it in its own timeseries collection/model and reference it from the parent

Example fix

// before
const tsSchema = new Schema({ t: Date, v: Number }, { timeseries: { timeField: 't' } });
new Schema({ metrics: tsSchema }); // throws

// after
const PointSchema = new Schema({ t: Date, v: Number });
new Schema({ metrics: [PointSchema] }); // embed plain points
mongoose.model('Measurement', tsSchema); // timeseries stays top-level

function assertEmbeddable(schema, path) {
  if (schema.options?.timeseries) {
    throw new Error(`cannot embed schema with timeseries option at ${path}`);
  }
}

const isEmbeddableSchema = schema => !schema?.options?.timeseries;

When it happens

Trigger: `new Schema({ metrics: new Schema({ t: Date, v: Number }, { timeseries: { timeField: 't', metaField: 'm', granularity: 'hours' } }) })` — any nested use of a timeseries schema.

Common situations: Refactoring a standalone timeseries model into a parent model; sharing one base schema between a timeseries collection and embedded subdocuments via utils.pick/clone that copy options.

Related errors

• Invalid sort() argument. Must be a string or object.
• Cannot create use schema for property "${key}" because the s
• Tried to set nested object field `${path}` to ${typeDescript
• Cannot set default value of path `${this.path}` to a mongoos
• Aggregate `near()` must be called with non-nullish argument

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