Invalid ${name}: cannot be empty or whitespace-only. Provide

Error message

Invalid ${name}: cannot be empty or whitespace-only. Provide a valid identifier.

What it means

Thrown by validateAndTrimEntityId when an entity id (userId, agentId, runId, etc. under filters) is a string that is empty or contains only whitespace after trimming. The SDK coerces values to strings and trims them, and rejects ids that would be blank because they cannot meaningfully scope memory. The error names which identifier is invalid.

Source

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

}

/**
 * Validates and normalizes an entity ID.
 * - Coerces non-string ids (e.g. numeric database keys) to string
 * - 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)) {

View on GitHub (pinned to 001c235229)

Solutions

Provide a non-empty id: filters: { userId: 'u1' } — check the variable actually holds a value before the call.
If the id comes from optional input, guard upstream: if (!id?.trim()) skip or fetch a real id instead of calling with ''.
Replace || '' defaults with meaningful fallbacks or fail-fast validation at the API boundary.
Trim ids once at ingestion so stored scoping is clean.

Example fix

// before
await memory.add(text, { filters: { userId: user?.id ?? '' } }); // throws when blank

// after
const userId = user?.id?.trim();
if (!userId) throw new Error('userId required to store memory');
await memory.add(text, { filters: { userId } });

Defensive patterns

Strategy: type-guard

Validate before calling

function requireEntityId(value: unknown, name: string): string {
  const trimmed = value == null ? '' : String(value).trim();
  if (trimmed === '') throw new TypeError(`${name} is required`);
  return trimmed;
}

Type guard

function isValidEntityId(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 be empty or whitespace-only/.test(err.message)) {
    return skipOrPromptForId(); // recover: ask for the id instead of crashing the flow
  }
  throw err;
}

Prevention

Never default ids to '' — throw or skip upstream when the id source is empty.
Trim ids at ingestion from users/CSVs/APIs before they reach Memory calls.
Share one requireEntityId helper across all call sites so validation is uniform.

When it happens

Trigger: Passing filters: { userId: '' }, { userId: ' ' }, or a value that stringifies to blank (e.g. an empty variable) to add/search/getAll/deleteAll etc. Also filters built from template strings where the variable is unset, like `user-${id}` with id undefined producing literal text — no, blank only when the whole result trims to empty, e.g. String(null) is 'null' but '' or ' ' pass through.

Common situations: Defaulting ids to empty string (userId = process.env.USER_ID || ''), reading ids from JSON/headers that are absent, whitespace copied from user input or CSV data, or test fixtures with placeholder blank ids.

Related errors

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