Automattic/mongoose · error · CastError

Cast to Boolean failed for value "${value}" (type ${valueTyp

Error message

Cast to Boolean failed for value "${value}" (type ${valueType}) at path "${path}"

What it means

SchemaBoolean.cast accepts booleans plus values registered in the convertToTrue/convertToFalse maps (0/1, '0'/'1', 'true'/'false', 'yes'/'no' by default); anything else is rejected as CastError Boolean rather than guessed truthiness.

Source

Thrown at lib/schema/boolean.js:235

 * @param {object} value
 * @param {object} model this value is optional
 * @api private
 */

SchemaBoolean.prototype.cast = function(value) {
  let castBoolean;
  if (typeof this._castFunction === 'function') {
    castBoolean = this._castFunction;
  } else if (typeof this.constructor.cast === 'function') {
    castBoolean = this.constructor.cast();
  } else {
    castBoolean = SchemaBoolean.cast();
  }

  try {
    return castBoolean(value);
  } catch (error) {
    throw new CastError('Boolean', value, this.path, error, this);
  }
};

const $conditionalHandlers = { ...SchemaType.prototype.$conditionalHandlers };

/**
 * Contains the handlers for different query operators for this schema type.
 * For example, `$conditionalHandlers.$in` is the function Mongoose calls to cast `$in` filter operators.
 *
 * @property $conditionalHandlers
 * @memberOf SchemaBoolean
 * @instance
 * @api public
 */

Object.defineProperty(SchemaBoolean.prototype, '$conditionalHandlers', {
  enumerable: false,
  value: $conditionalHandlers

View on GitHub (pinned to 49cdab0136)

Solutions

Normalize at the boundary: map 'on'/'checked' to true, 'off'/absent to false before assignment.
Extend the maps: mongoose.Schema.Types.Boolean.convertToTrue.add('on') and convertToFalse.add('off') - they are Sets.
Reject with a 400 when the value is not in your accepted boolean vocabulary.

Example fix

// before
doc.subscribed = req.body.subscribed; // 'on' -> CastError Boolean

// after (once at bootstrap):
mongoose.Schema.Types.Boolean.convertToTrue.add('on');
mongoose.Schema.Types.Boolean.convertToFalse.add('off');
// then:
doc.subscribed = req.body.subscribed;

Defensive patterns

Strategy: validation

Validate before calling

const toBool = (v) => {
  if (typeof v === 'boolean') return v;
  if (mongoose.Schema.Types.Boolean.convertToTrue.has(v)) return true;
  if (mongoose.Schema.Types.Boolean.convertToFalse.has(v)) return false;
  throw new TypeError(`not a recognized boolean: ${String(v)}`);
};
doc.subscribed = toBool(req.body.subscribed);

Type guard

const isCastableBoolean = (v) =>
  typeof v === 'boolean' ||
  mongoose.Schema.Types.Boolean.convertToTrue.has(v) ||
  mongoose.Schema.Types.Boolean.convertToFalse.has(v);

Prevention

Convert form encodings ('on'/'off', checkbox presence) to real booleans in the controller.
Register extra truthy/falsy words once at bootstrap if your users send them.
Keep one shared boolean vocabulary across API and schema.

When it happens

Trigger: `doc.active = 'on'` (an HTML checkbox value); `doc.active = 2`; `doc.active = 'maybe'`; localized truthy words like 'si'/'oui' not present in the maps.

Common situations: HTML forms sending checkbox 'on' values; i18n truthy words; APIs serializing booleans as 'Y'/'N' or 1/2 codes.

Related errors

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