Automattic/mongoose · error · Error

Mongoose maps do not support keys that contain ".", got "${k

Error message

Mongoose maps do not support keys that contain ".", got "${key}"

What it means

checkValidKey() rejects Map keys containing '.', because Mongoose and MongoDB use dots as path separators. A dotted key would be ambiguous with nested paths in updates and queries, so it is refused.

Source

Thrown at lib/types/map.js:361

});

/**
 * Since maps are stored as objects under the hood, keys must be strings
 * and can't contain any invalid characters
 * @param {string} key
 * @api private
 */

function checkValidKey(key) {
  const keyType = typeof key;
  if (keyType !== 'string') {
    throw new TypeError(`Mongoose maps only support string keys, got ${keyType}`);
  }
  if (key.startsWith('$')) {
    throw new Error(`Mongoose maps do not support keys that start with "$", got "${key}"`);
  }
  if (key.includes('.')) {
    throw new Error(`Mongoose maps do not support keys that contain ".", got "${key}"`);
  }
  if (specialProperties.has(key)) {
    throw new Error(`Mongoose maps do not support reserved key name "${key}"`);
  }
}

module.exports = MongooseMap;

View on GitHub (pinned to 49cdab0136)

Solutions

1. Replace dots with a safe delimiter: key.split('.').join(':') or key.replaceAll('.', '_')
2. Use URL-encoding for arbitrary keys: encodeURIComponent(key)
3. Model dotted identifiers as separate fields or an array of subdocuments instead of a Map

Example fix

// before
doc.logins.set('user@example.com', new Date());
// after
doc.logins.set('user@example~com', new Date()); // dot replaced

function encodeMapKey(key) {
  const k = String(key);
  if (k.includes('.')) return k.split('.').join('\u2024'); // or '_'
  return k;
}
doc.index.set(encodeMapKey('user@example.com'), v);

function isDotFreeKey(key) { return !String(key).includes('.'); }

try { doc.index.set(k, v); } catch (err) { if (/contain "\."/.test(err.message)) doc.index.set(k.replaceAll('.', '_'), v); else throw err; }

When it happens

Trigger: doc.emails.set('user@example.com', data) — email contains a dot; keys derived from file paths, domain names, version strings ('1.2.3'), or dotted identifiers from user input.

Common situations: Using emails, hostnames, file paths, or semantic-version strings as Map keys; porting objects that allowed dots to a Mongoose Map.

Related errors

• Mongoose maps only support string keys, got ${keyType}
• Mongoose maps do not support keys that start with "$", got "
• Mongoose maps do not support reserved key name "${key}"
• Field `${path}` is not in schema and strict mode is set to t
• Cannot use schema-level projections (`select: true` or `sele

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