{"record":{"id":"b35e4d9fc7666f6f","repo":"Automattic/mongoose","slug":"cannot-convert-a-buffer-with-subtype-this-subty","errorCode":null,"errorMessage":"Cannot convert a Buffer with subtype ${this._subtype} to a UUID","messagePattern":"Cannot convert a Buffer with subtype (.+?) to a UUID","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/types/buffer.js","lineNumber":222,"sourceCode":" * @memberOf MongooseBuffer\n */\n\nMongooseBuffer.mixin.toBSON = function() {\n  return new Binary(this, this._subtype || 0);\n};\n\n/**\n * Converts this buffer to a UUID. Throws an error if subtype is not 4.\n *\n * @return {UUID}\n * @api public\n * @method toUUID\n * @memberOf MongooseBuffer\n */\n\nMongooseBuffer.mixin.toUUID = function() {\n  if (this._subtype !== 4) {\n    throw new Error('Cannot convert a Buffer with subtype ' + this._subtype + ' to a UUID');\n  }\n  return new UUID(this);\n};\n\n/**\n * Determines if this buffer is equals to `other` buffer\n *\n * @param {Buffer} other\n * @return {boolean}\n * @method equals\n * @memberOf MongooseBuffer\n */\n\nMongooseBuffer.mixin.equals = function(other) {\n  if (!Buffer.isBuffer(other)) {\n    return false;\n  }\n","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/types/buffer.js#L204-L240","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set the subtype to 4 before converting: buf.subtype(bson.BSON_BINARY_SUBTYPE_UUID); buf.toUUID()","Prefer declaring the field as Schema.Types.UUID so Mongoose handles subtype 4 and conversion automatically","For subtype-3 legacy data, re-store it as subtype 4 or convert manually via the BSON UUID class"],"exampleFix":"// before\nconst uuid = doc.bin.toUUID(); // subtype 0\n// after\ndoc.bin.subtype(4); // bson.BSON_BINARY_SUBTYPE_UUID\nconst uuid = doc.bin.toUUID();","handlingStrategy":"type-guard","validationCode":"function bufferToUUID(buf) {\n  if (buf._subtype !== 4) throw new TypeError('Buffer subtype must be 4 (UUID) for conversion');\n  return buf.toUUID();\n}","typeGuard":"function isUUIDBuffer(buf) { return Buffer.isBuffer(buf) && buf._subtype === 4; }","tryCatchPattern":"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; }","preventionTips":["Declare UUID fields as Schema.Types.UUID rather than Buffer","Set subtype(4) immediately after creating binary UUID buffers","Validate legacy binary data's subtype before attempting UUID conversion"],"tags":["mongoose","buffer","uuid","bson"],"backgroundTag":"uuid-conversion-failed","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}