Automattic/mongoose · error · MongooseError

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

Error message

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

What it means

When a path's `alias` option is not an array, Mongoose requires it to be a single string; any other truthy type (number, boolean, object) throws at schema construction with the path and the bad value in the message. Aliases are implemented as virtuals, and virtual names must be strings, so Mongoose rejects the schema immediately.

Source

Thrown at lib/schema.js:236

            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);
            };
          })(prop));
      }

      continue;
    }

    if (typeof alias !== 'string') {
      throw new MongooseError('Invalid value for alias option on ' + prop + ', got ' + alias);
    }

    schema.aliases[alias] = prop;

    schema.
      virtual(alias).
      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. Pass a string: `alias: 'title'` (or an array of strings for multiple aliases).
2. Validate config values before building the schema: `if (typeof aliasValue === 'string') opts.alias = aliasValue;`.
3. Remember alias points from the virtual name to the real path: put the new name in alias, the stored name in the schema key.

Example fix

// before
new Schema({ name: { type: String, alias: { displayName: 'name' } } }); // throws

// after
new Schema({ name: { type: String, alias: 'displayName' } }); // doc.displayName reads/writes doc.name

function assertAlias(alias) {
  if (alias == null) return;
  const ok = typeof alias === 'string' || (Array.isArray(alias) && alias.every(a => typeof a === 'string'));
  if (!ok) throw new TypeError(`alias must be a string or string[], got ${typeof alias}`);
}

const isValidAlias = (a) => a == null || typeof a === 'string' || (Array.isArray(a) && a.every(x => typeof x === 'string'));

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

When it happens

Trigger: `new Schema({ name: { type: String, alias: 5 } })`; `alias: true`; `alias: { displayName: 'name' }` (object used as a reverse map); alias values sourced from unvalidated env/config.

Common situations: Config-driven schemas where the alias field comes from YAML/JSON and arrives as a number or boolean; misunderstanding alias direction (it maps alias → real path, not the reverse).

Related errors

• Invalid value for alias option on ${prop}, got ${a}
• 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/a149041af06be003. Report an issue: GitHub.