{"record":{"id":"3ee09f83900816be","repo":"Automattic/mongoose","slug":"mongoose-maps-only-support-string-keys-got-keyt","errorCode":null,"errorMessage":"Mongoose maps only support string keys, got ${keyType}","messagePattern":"Mongoose maps only support string keys, got (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"lib/types/map.js","lineNumber":355,"sourceCode":"\nObject.defineProperty(MongooseMap.prototype, '$__deferredCalls', {\n  enumerable: false,\n  writable: false,\n  configurable: false,\n  value: true\n});\n\n/**\n * Since maps are stored as objects under the hood, keys must be strings\n * and can't contain any invalid characters\n * @param {string} key\n * @api private\n */\n\nfunction checkValidKey(key) {\n  const keyType = typeof key;\n  if (keyType !== 'string') {\n    throw new TypeError(`Mongoose maps only support string keys, got ${keyType}`);\n  }\n  if (key.startsWith('$')) {\n    throw new Error(`Mongoose maps do not support keys that start with \"$\", got \"${key}\"`);\n  }\n  if (key.includes('.')) {\n    throw new Error(`Mongoose maps do not support keys that contain \".\", got \"${key}\"`);\n  }\n  if (specialProperties.has(key)) {\n    throw new Error(`Mongoose maps do not support reserved key name \"${key}\"`);\n  }\n}\n\nmodule.exports = MongooseMap;\n","sourceCodeStart":337,"sourceCodeEnd":369,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/types/map.js#L337-L369","documentation":"checkValidKey() guards every key written to a MongooseMap. Because Maps are persisted as plain MongoDB objects, keys must be strings; setting a numeric, boolean, symbol, or object key throws a TypeError.","triggerScenarios":"doc.map.set(123, 'x'); doc.map.set(user.id, ...) where user.id is a number or ObjectId; constructing the Map from Object.entries of typed input; using m.set(Symbol('k'), v).","commonSituations":"Numeric IDs from external systems used as Map keys; values coming from typed APIs, query strings, or BSON types that are not strings.","solutions":["Convert keys to strings when setting: doc.map.set(String(key), value)","Declare the Map with string-friendly keys at the boundary: { type: Map, of: String } and normalize input before assignment","For ObjectId keys, use the hex string: doc.map.set(id.toHexString(), v)"],"exampleFix":"// before\ndoc.clicks.set(42, 'x'); // TypeError\n// after\ndoc.clicks.set(String(42), 'x');","handlingStrategy":"type-guard","validationCode":"function safeMapSet(map, key, value) {\n  if (typeof key !== 'string') key = String(key);\n  map.set(key, value);\n}","typeGuard":"function isStringKey(key) { return typeof key === 'string'; }","tryCatchPattern":"try { doc.map.set(key, val); } catch (err) { if (/only support string keys/.test(err.message)) doc.map.set(String(key), val); else throw err; }","preventionTips":["Normalize external keys with String() before Map writes","Use toHexString() for ObjectId keys","Unit-test Map writes with the exact key types your ingesters produce"],"tags":["mongoose","map","keys","typeerror"],"backgroundTag":"invalid-map-key","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}