{"record":{"id":"dcec9933e6a2807a","repo":"mastra-ai/mastra","slug":"metadata-key-key-exceeds-maximum-length-of","errorCode":null,"errorMessage":"Metadata key \"${key}\" exceeds maximum length of ${MAX_METADATA_KEY_LENGTH} characters.","messagePattern":"Metadata key \"(.+?)\" exceeds maximum length of (.+?) characters\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/memory/base.ts","lineNumber":441,"sourceCode":"  protected validateMetadataKeys(metadata: Record<string, unknown> | undefined): void {\n    if (!metadata) return;\n\n    for (const key of Object.keys(metadata)) {\n      // First check for disallowed prototype pollution keys\n      if (DISALLOWED_METADATA_KEYS.has(key)) {\n        throw new Error(`Invalid metadata key: \"${key}\".`);\n      }\n\n      // Then check pattern\n      if (!SAFE_METADATA_KEY_PATTERN.test(key)) {\n        throw new Error(\n          `Invalid metadata key: \"${key}\". Keys must start with a letter or underscore and contain only alphanumeric characters and underscores.`,\n        );\n      }\n\n      // Also limit key length to prevent potential issues\n      if (key.length > MAX_METADATA_KEY_LENGTH) {\n        throw new Error(`Metadata key \"${key}\" exceeds maximum length of ${MAX_METADATA_KEY_LENGTH} characters.`);\n      }\n    }\n  }\n\n  /**\n   * Validates pagination parameters and returns safe offset.\n   * @param page - Page number (0-indexed)\n   * @param perPage - Items per page (0 is allowed and returns empty results)\n   * @throws Error if page is negative, perPage is negative/invalid, or offset would overflow\n   */\n  protected validatePagination(page: number, perPage: number): void {\n    if (!Number.isFinite(page) || !Number.isSafeInteger(page) || page < 0) {\n      throw new Error('page must be >= 0');\n    }\n\n    // perPage: 0 is allowed (returns empty results), negative values are rejected\n    if (!Number.isFinite(perPage) || !Number.isSafeInteger(perPage) || perPage < 0) {\n      throw new Error('perPage must be >= 0');","sourceCodeStart":423,"sourceCodeEnd":459,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/memory/base.ts#L423-L459","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Shorten the metadata key to within the limit (use a short stable name and put the long data in the value).","Hash or truncate long identifiers before using them as keys (e.g. sha256 of the URL).","Check key.length against the library's MAX_METADATA_KEY_LENGTH constant before writing.","Store large payloads as metadata values or in dedicated storage rather than keys."],"exampleFix":"// before\nthread.metadata = { ['https://example.com/very/long/path/that/goes/on/and/on/...' ]: true };\n// after\nthread.metadata = { source_url_hash: sha256(url) };","handlingStrategy":"validation","validationCode":"function assertKeyLength(metadata) {\n  for (const key of Object.keys(metadata ?? {})) {\n    if (key.length > 255) throw new Error(`Metadata key too long: ${key.slice(0, 20)}...`);\n  }\n}","typeGuard":"function hasShortKeys(m: unknown): m is Record<string, unknown> {\n  return !!m && Object.keys(m).every(k => k.length <= 255);\n}","tryCatchPattern":"try {\n  await storage.listThreads(params);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('exceeds maximum length')) {\n    // truncate/hash keys and retry\n  } else throw e;\n}","preventionTips":["Hash long identifiers (URLs, blobs) before using them as keys","Keep long data in metadata values, not keys","Add a key-length unit test for metadata-building code"],"tags":["validation","storage","metadata"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}