Automattic/mongoose · error · Error

Cannot convert a Buffer with subtype ${this._subtype} to a U

Error message

Cannot convert a Buffer with subtype ${this._subtype} to a UUID

What it means

MongooseBuffer.toUUID() converts a BSON binary buffer to a UUID, which is only valid for binary subtype 4 (the UUID subtype). If the buffer was stored with a different subtype (e.g. the default 0 or subtype 3), the bytes are not a standard UUID representation, so the conversion is refused.

Source

Thrown at lib/types/buffer.js:222

 * @memberOf MongooseBuffer
 */

MongooseBuffer.mixin.toBSON = function() {
  return new Binary(this, this._subtype || 0);
};

/**
 * Converts this buffer to a UUID. Throws an error if subtype is not 4.
 *
 * @return {UUID}
 * @api public
 * @method toUUID
 * @memberOf MongooseBuffer
 */

MongooseBuffer.mixin.toUUID = function() {
  if (this._subtype !== 4) {
    throw new Error('Cannot convert a Buffer with subtype ' + this._subtype + ' to a UUID');
  }
  return new UUID(this);
};

/**
 * Determines if this buffer is equals to `other` buffer
 *
 * @param {Buffer} other
 * @return {boolean}
 * @method equals
 * @memberOf MongooseBuffer
 */

MongooseBuffer.mixin.equals = function(other) {
  if (!Buffer.isBuffer(other)) {
    return false;
  }

View on GitHub (pinned to 49cdab0136)

Solutions

1. Set the subtype to 4 before converting: buf.subtype(bson.BSON_BINARY_SUBTYPE_UUID); buf.toUUID()
2. Prefer declaring the field as Schema.Types.UUID so Mongoose handles subtype 4 and conversion automatically
3. For subtype-3 legacy data, re-store it as subtype 4 or convert manually via the BSON UUID class

Example fix

// before
const uuid = doc.bin.toUUID(); // subtype 0
// after
doc.bin.subtype(4); // bson.BSON_BINARY_SUBTYPE_UUID
const uuid = doc.bin.toUUID();

function bufferToUUID(buf) {
  if (buf._subtype !== 4) throw new TypeError('Buffer subtype must be 4 (UUID) for conversion');
  return buf.toUUID();
}

function isUUIDBuffer(buf) { return Buffer.isBuffer(buf) && buf._subtype === 4; }

try { return doc.bin.toUUID(); } catch (err) { if (/Cannot convert a Buffer with subtype/.test(err.message)) throw new Error('Field stored without UUID subtype — re-store as subtype 4 or use Schema.Types.UUID'); throw err; }

When it happens

Trigger: const u = doc.binaryField.toUUID() where the field was written with default subtype 0; calling toUUID() before setting doc.binaryField.subtype(bson.BSON_BINARY_SUBTYPE_UUID).

Common situations: Reading legacy binary data written without a subtype; writing UUIDs via raw driver inserts (subtype 3, legacy UUID) then reading through a Mongoose Schema.Types.Buffer field.

Related errors

• Invalid subtype. Expected a number
• "${value}" is not a valid UUID string
• "${value}" cannot be casted to a UUID
• a circular reference in the update value, updateValue: ${uti
• Cast to Buffer failed for value "${value}" (type ${valueType

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