Automattic/mongoose · error · MongooseError

Invalid value for alias option on ${prop}, got ${a}

Error message

Invalid value for alias option on ${prop}, got ${a}

What it means

A schema path declared `alias: [...]` must contain only strings; when Mongoose builds aliases at schema-construction time it iterates the array and throws for any non-string entry, naming the path and the offending value. The alias mechanism creates a virtual per alias that reads/writes the real path, which only works for string virtual names.

Source

Thrown at lib/schema.js:210

      alias = paths[path];
    } else {
      const options = get(schema.paths[path], 'options');
      if (options == null) {
        continue;
      }

      alias = options.alias;
    }

    if (!alias) {
      continue;
    }

    const prop = schema.paths[path].path;
    if (Array.isArray(alias)) {
      for (const a of alias) {
        if (typeof a !== 'string') {
          throw new MongooseError('Invalid value for alias option on ' + prop + ', got ' + a);
        }

        schema.aliases[a] = prop;

        schema.
          virtual(a).
          get((function(p) {
            return function() {
              if (typeof this.get === 'function') {
                return this.get(p);
              }
              return this[p];
            };
          })(prop)).
          set((function(p) {
            return function(v) {
              return this.$set(p, v);
            };

View on GitHub (pinned to 49cdab0136)

Solutions

1. Use only string aliases: `alias: ['n', 'title']`.
2. Filter/validate config-driven aliases before schema creation: `aliases.filter(a => typeof a === 'string')`.
3. Fail fast in tests by instantiating every generated schema once during startup.

Example fix

// before
new Schema({ name: { type: String, alias: ['n', 5] } }); // throws: Invalid value for alias option on name, got 5

// after
new Schema({ name: { type: String, alias: ['n', 'title'] } });

function sanitizeAliases(aliases) {
  if (aliases == null) return undefined;
  const list = Array.isArray(aliases) ? aliases : [aliases];
  const clean = list.filter(a => typeof a === 'string');
  if (clean.length !== list.length) throw new TypeError('All aliases must be strings');
  return Array.isArray(aliases) ? clean : clean[0];
}

const aliasesAreValid = (list) => Array.isArray(list) && list.every(a => typeof a === 'string');

try { return new Schema(def); } catch (err) { if (err instanceof mongoose.Error && /Invalid value for alias option/.test(err.message)) { /* fix the alias config entry and rebuild */ } throw err; }

When it happens

Trigger: `new Schema({ name: { type: String, alias: ['n', 5] } })`; alias arrays containing null, booleans, or objects; building alias arrays from config or user input without type checks.

Common situations: Generating schemas from config files or JSON where a numeric alias slips in; typos like `alias: ['n', null]`; refactors that leave placeholder values in alias arrays.

Related errors

• Invalid value for alias option on ${prop}, got ${alias}
• Schema#pick() only accepts an array argument, got "${typeof
• Invalid addFields() argument. Must be an object
• Aggregate `near()` must be called with non-nullish argument
• Invalid sort() argument. Must be a string or object.

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