Automattic/mongoose · error · TypeError

Invalid schema configuration: `${name}` is not a valid type

Error message

Invalid schema configuration: `${name}` is not a valid type at path `${path}`. See https://bit.ly/mongoose-schematypes for a list of valid schema types.

What it means

Mongoose resolves every schema path definition to a SchemaType class by looking the type's constructor name up in its registry (Schema.Types / MongooseTypes). This error means the name resolved for `path` has no registered SchemaType, so the path cannot be represented and the schema build fails immediately rather than producing a silently unusable path.

Source

Thrown at lib/schema.js:1797

    name = name.charAt(0).toUpperCase() + name.substring(1);
  }
  // Special case re: gh-7049 because the bson `ObjectID` class' capitalization
  // doesn't line up with Mongoose's.
  if (name === 'ObjectID') {
    name = 'ObjectId';
  }
  // For Jest 26+, see #10296
  if (name === 'ClockDate') {
    name = 'Date';
  }

  if (name === void 0) {
    throw new TypeError(`Invalid schema configuration: \`${path}\` schematype definition is ` +
      'invalid. See ' +
      'https://mongoosejs.com/docs/guide.html#definition for more info on supported schema syntaxes.');
  }
  if (MongooseTypes[name] == null) {
    throw new TypeError(`Invalid schema configuration: \`${name}\` is not ` +
      `a valid type at path \`${path}\`. See ` +
      'https://bit.ly/mongoose-schematypes for a list of valid schema types.');
  }

  const schemaType = new MongooseTypes[name](path, obj, options, this);

  return schemaType;
};

/**
 * Iterates the schemas paths similar to Array#forEach.
 *
 * The callback is passed the pathname and the schemaType instance.
 *
 * #### Example:
 *
 *     const userSchema = new Schema({ name: String, registeredAt: Date });
 *     userSchema.eachPath((pathname, schematype) => {

View on GitHub (pinned to 49cdab0136)

Solutions

1. Log the imported symbol before `new Schema(...)` - `undefined` almost always means a circular import or the wrong import form (default vs named).
2. Spell built-ins exactly: String, Number, Date, Boolean, Buffer, Map, Mixed, ObjectId, BigInt, UUID, or mongoose.Schema.Types.X.
3. Register custom SchemaTypes before use: mongoose.Schema.Types.MyType = MySchemaType (or use an established mongoose-type package).
4. Upgrade to a mongoose version that ships the type you reference (BigInt needs >= 6.x, UUID needs >= 6.10).
5. Use Schema.Types.Mixed for genuinely arbitrary payloads instead of an unregistered class.

Example fix

// before
class EmailType extends mongoose.SchemaType {}
// circular require leaves EmailType undefined at schema-definition time:
module.exports = { schema: new Schema({ contact: { type: require('./email').EmailType } }) };

// after
const { EmailType } = require('./email'); // import once the module graph resolves
mongoose.Schema.Types.Email = EmailType; // register once at bootstrap
const s = new Schema({ contact: EmailType });

const assertValidTypes = (def) => {
  for (const [path, opts] of Object.entries(def)) {
    const t = opts && opts.type ? opts.type : opts;
    if (typeof t !== 'function') continue; // nested pojo
    if (mongoose.Schema.Types[t.name] == null) {
      throw new Error(`path ${path}: type ${t.name} is not a registered SchemaType`);
    }
  }
};
assertValidTypes(myDefinition);
const schema = new Schema(myDefinition);

const isRegisteredSchemaType = (t) =>
  typeof t === 'function' &&
  mongoose.Schema.Types[t.name] != null;

try { new Schema(def); } catch (err) { if (err instanceof TypeError && err.message.includes('not a valid type')) { /* log the definition and imported symbols, fail startup */ } throw err; }

When it happens

Trigger: A path whose `type` is unregistered: `{ type: undefined }` caused by a circular import or wrong default/named import, a typo like `{ type: Strring }`, a project class never registered with mongoose, or referencing a type your mongoose version does not ship (e.g. BigInt/UUID on old versions). Also `new Schema({ x: MyUnregisteredClass })` directly.

Common situations: Circular requires between schema modules that leave an imported type undefined at definition time; TypeScript/ESM interop mixing default and named imports; downgrading mongoose and losing newer types; copy-pasted schemas referencing classes from another package.

Related errors

• 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
• Aggregate.prototype.explain() no longer accepts a callback
• 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/2c6b6f6c6a2fed49. Report an issue: GitHub.