mastra-ai/mastra · error

Metadata key "${key}" exceeds maximum length of ${MAX_METADA

Error message

Metadata key "${key}" exceeds maximum length of ${MAX_METADATA_KEY_LENGTH} characters.

What it means

Metadata keys are length-limited to MAX_METADATA_KEY_LENGTH characters to protect storage backends from oversized keys that degrade indexing, query, and serialization performance. A key longer than the limit is rejected at validation time.

Source

Thrown at packages/core/src/storage/domains/memory/base.ts:441

  protected validateMetadataKeys(metadata: Record<string, unknown> | undefined): void {
    if (!metadata) return;

    for (const key of Object.keys(metadata)) {
      // First check for disallowed prototype pollution keys
      if (DISALLOWED_METADATA_KEYS.has(key)) {
        throw new Error(`Invalid metadata key: "${key}".`);
      }

      // Then check pattern
      if (!SAFE_METADATA_KEY_PATTERN.test(key)) {
        throw new Error(
          `Invalid metadata key: "${key}". Keys must start with a letter or underscore and contain only alphanumeric characters and underscores.`,
        );
      }

      // Also limit key length to prevent potential issues
      if (key.length > MAX_METADATA_KEY_LENGTH) {
        throw new Error(`Metadata key "${key}" exceeds maximum length of ${MAX_METADATA_KEY_LENGTH} characters.`);
      }
    }
  }

  /**
   * Validates pagination parameters and returns safe offset.
   * @param page - Page number (0-indexed)
   * @param perPage - Items per page (0 is allowed and returns empty results)
   * @throws Error if page is negative, perPage is negative/invalid, or offset would overflow
   */
  protected validatePagination(page: number, perPage: number): void {
    if (!Number.isFinite(page) || !Number.isSafeInteger(page) || page < 0) {
      throw new Error('page must be >= 0');
    }

    // perPage: 0 is allowed (returns empty results), negative values are rejected
    if (!Number.isFinite(perPage) || !Number.isSafeInteger(perPage) || perPage < 0) {
      throw new Error('perPage must be >= 0');

View on GitHub (pinned to 75dd419e61)

Solutions

1. Shorten the metadata key to within the limit (use a short stable name and put the long data in the value).
2. Hash or truncate long identifiers before using them as keys (e.g. sha256 of the URL).
3. Check key.length against the library's MAX_METADATA_KEY_LENGTH constant before writing.
4. Store large payloads as metadata values or in dedicated storage rather than keys.

Example fix

// before
thread.metadata = { ['https://example.com/very/long/path/that/goes/on/and/on/...' ]: true };
// after
thread.metadata = { source_url_hash: sha256(url) };

function assertKeyLength(metadata) {
  for (const key of Object.keys(metadata ?? {})) {
    if (key.length > 255) throw new Error(`Metadata key too long: ${key.slice(0, 20)}...`);
  }
}

function hasShortKeys(m: unknown): m is Record<string, unknown> {
  return !!m && Object.keys(m).every(k => k.length <= 255);
}

try {
  await storage.listThreads(params);
} catch (e) {
  if (e instanceof Error && e.message.includes('exceeds maximum length')) {
    // truncate/hash keys and retry
  } else throw e;
}

When it happens

Trigger: Saving or listing a thread whose metadata contains a key longer than MAX_METADATA_KEY_LENGTH characters, e.g. embedding a long URL, JSON blob, or generated identifier as the key.

Common situations: Using full URLs or base64 blobs as metadata keys; accidental object spread where a long string value became a key; programmatic key generation without a length check.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid metadata key: "${key}".
• Invalid metadata key: "${key}". Keys must start with a lette
• Metadata filter must be an object.
• Invalid metadata filter key "${key}".
• Invalid metadata filter value for key "${key}". Values must

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/dcec9933e6a2807a. Report an issue: GitHub.