{"record":{"id":"017b5401837d29bb","repo":"mastra-ai/mastra","slug":"invalid-field-key-segment-segment-in-key","errorCode":null,"errorMessage":"Invalid field key segment: ${segment} in ${key}","messagePattern":"Invalid field key segment: (.+?) in (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/utils.ts","lineNumber":623,"sourceCode":" *   - Start with a letter (a-z, A-Z) or underscore (_)\n *   - Contain only letters, numbers, or underscores\n *   - Be at most 63 characters long\n *\n * @param key - The dot-separated field key string to parse.\n * @returns The validated field key as a branded type.\n * @throws {Error} If any segment of the key is invalid.\n *\n * @example\n * const key = parseFieldKey('user_profile.name'); // Ok\n * parseFieldKey('user..name'); // Throws error\n * parseFieldKey('user.123name'); // Throws error\n */\nexport function parseFieldKey(key: string): FieldKey {\n  if (!key) throw new Error('Field key cannot be empty');\n  const segments = key.split('.');\n  for (const segment of segments) {\n    if (!SQL_IDENTIFIER_PATTERN.test(segment) || segment.length > 63) {\n      throw new Error(`Invalid field key segment: ${segment} in ${key}`);\n    }\n  }\n  return key as FieldKey;\n}\n\n/**\n * Removes specific keys from an object.\n * @param obj - The original object\n * @param keysToOmit - Keys to exclude from the returned object\n * @returns A new object with the specified keys removed\n */\nexport function omitKeys<T extends Record<string, any>>(obj: T, keysToOmit: string[]): Partial<T> {\n  return Object.fromEntries(Object.entries(obj).filter(([key]) => !keysToOmit.includes(key))) as Partial<T>;\n}\n\n/**\n * Selectively extracts specific fields from an object using dot notation.\n * Does not error if fields don't exist - simply omits them from the result.","sourceCodeStart":605,"sourceCodeEnd":641,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/utils.ts#L605-L641","documentation":"`parseFieldKey` splits dotted field keys (e.g. `metadata.user.name`) and validates every segment against `SQL_IDENTIFIER_PATTERN` plus a 63-char limit. Any segment that is empty, contains invalid characters, or is too long throws this error naming the offending segment and the full key — protecting JSON path construction and column quoting from malformed keys.","triggerScenarios":"Passing keys like `user..name` (empty segment), `user.123name` (segment starting with a digit), `user name.first` (space), `user.first-name` (hyphen), or a segment over 63 chars to `column`, `buildJsonPath`, `sanitizeColumn`, `field`, etc.","commonSituations":"Building JSON paths from user-supplied metadata keys that contain dashes or dots-in-key-names; camelCase vs kebab-case mismatch where kebab keys reach SQL; numeric-leading keys from JSON data.","solutions":["Ensure each dot-separated segment matches `[A-Za-z_][A-Za-z0-9_]{0,62}`; sanitize segments with `seg.replace(/[^A-Za-z0-9_]/g, '_')`.","For keys that legitimately contain special characters, store them under a safe wrapper key (e.g. `data[\"first-name\"]` addressed via a different accessor) instead of a dotted field key.","Validate/sanitize user-derived metadata keys at ingestion time so they are field-key safe downstream."],"exampleFix":"// before\nbuildJsonPath('user.first-name'); // hyphen rejected\n// after\nbuildJsonPath('user.first_name');","handlingStrategy":"validation","validationCode":"function sanitizeFieldKey(key: string): string {\n  return key.split('.').map(s => s.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 63)).join('.');\n}\n// sanitizeFieldKey('user.first-name') -> 'user.first_name'","typeGuard":"function isValidFieldKey(key: string): boolean {\n  return key.split('.').every(s => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s) && s.length <= 63);\n}","tryCatchPattern":"let path: FieldKey;\ntry {\n  path = parseFieldKey(metadataPath);\n} catch (e) {\n  path = parseFieldKey(sanitizeFieldKey(metadataPath));\n}","preventionTips":["Sanitize metadata/JSON keys at ingestion so every dot-segment is `[A-Za-z_][A-Za-z0-9_]`.","Store keys containing hyphens or leading digits under a safe wrapper key instead of dotted paths.","Linter rule or test asserting all dotted key constants used with storage APIs pass isValidFieldKey."],"tags":["sql","validation","field-key","json-path"],"backgroundTag":"invalid-field-key","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}