Invalid ${name}: cannot contain whitespace. Provide a valid

Error message

Invalid ${name}: cannot contain whitespace. Provide a valid identifier without spaces.

What it means

Thrown by validateAndTrimEntityId when an entity id trims to a non-empty string but still contains internal whitespace (spaces, tabs, newlines). Because ids are used as vector-store and history keys, embedded whitespace is rejected to prevent subtle matching/key bugs; the error names the offending parameter.

Source

Thrown at mem0-ts/src/oss/src/memory/index.ts:173

 * - Trims leading/trailing whitespace
 * - Rejects empty or whitespace-only strings
 * - Rejects strings containing internal whitespace
 * @returns The trimmed entity ID, or undefined if input is undefined/null
 * @throws Error if entity ID is invalid
 */
function validateAndTrimEntityId(
  value: string | number | undefined | null,
  name: string,
): string | undefined {
  if (value == null) return undefined;
  const trimmed = String(value).trim();
  if (trimmed === "") {
    throw new Error(
      `Invalid ${name}: cannot be empty or whitespace-only. Provide a valid identifier.`,
    );
  }
  if (/\s/.test(trimmed)) {
    throw new Error(
      `Invalid ${name}: cannot contain whitespace. Provide a valid identifier without spaces.`,
    );
  }
  return trimmed;
}

/**
 * Validates search parameters.
 * @throws Error if threshold or topK are invalid
 */
function validateSearchParams(threshold?: number, topK?: number): void {
  if (threshold !== undefined) {
    if (typeof threshold !== "number" || isNaN(threshold)) {
      throw new Error("threshold must be a valid number");
    }
    if (threshold < 0 || threshold > 1) {
      throw new Error(
        `Invalid threshold: ${threshold}. Must be between 0 and 1 (inclusive).`,

View on GitHub (pinned to 001c235229)

Solutions

Use a real identifier: slugify or hash free-text ('ada-lovelace', or a UUID) before passing it as an entity id.
If concatenating fields, join with a safe separator like '-' or '_'.
Sanitize once at the boundary: id.trim().replace(/\s+/g, '-') before calling Memory APIs.
Prefer stable machine ids (UUIDs, database keys) over human-readable names.

Example fix

// before
await memory.add(text, { filters: { userId: `${firstName} ${lastName}` } }); // 'Ada Lovelace' throws

// after
const userId = `${firstName}-${lastName}`.trim().replace(/\s+/g, '-');
await memory.add(text, { filters: { userId } }); // 'Ada-Lovelace'

Defensive patterns

Strategy: type-guard

Validate before calling

function slugifyId(value: string): string {
  return value.trim().replace(/\s+/g, '-');
}

Type guard

function isWhitespaceFreeId(value: unknown): value is string {
  return typeof value === 'string' && value.trim() !== '' && !/\s/.test(value.trim());
}

Try / catch

try {
  await memory.add(text, { filters: { userId } });
} catch (err) {
  if (err instanceof Error && /cannot contain whitespace/.test(err.message)) {
    await memory.add(text, { filters: { userId: userId.replace(/\s+/g, '-') } });
    return;
  }
  throw err;
}

Prevention

Prefer UUIDs or database keys as entity ids over names/emails.
Build composite ids with '-' or '_' separators, never spaces.
Sanitize all externally sourced ids through a single slugify step.

When it happens

Trigger: Passing filters: { userId: 'user 1' }, { agentId: 'agent\t1' }, or an id containing a newline — any /\s/ match inside the trimmed value. Common when ids are built by concatenation with spaces or taken from free-text fields instead of true identifiers.

Common situations: Using display names or emails with spaces as ids ('Ada Lovelace'), concatenating fields with ' ' separators, pasted ids with stray whitespace or line breaks, or generating ids via template literals that include spaces.

Related errors

AI-assisted analysis of mem0ai/mem0@001c235229 (2026-08-15). Data as JSON: /api/errors/dfb9e1c511811186. Report an issue: GitHub.