{"record":{"id":"765533c31d6266c9","repo":"mastra-ai/mastra","slug":"field-key-cannot-be-empty","errorCode":null,"errorMessage":"Field key cannot be empty","messagePattern":"Field key cannot be empty","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/utils.ts","lineNumber":619,"sourceCode":"\n/**\n * Parses and returns a valid dot-separated SQL field key (e.g., 'user.profile.name').\n * Each segment must:\n *   - 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}","sourceCodeStart":601,"sourceCodeEnd":637,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/utils.ts#L601-L637","documentation":"`parseFieldKey` rejects empty field keys passed to storage/SQL field APIs (column selection, JSON path building, sanitization). A falsy key would produce invalid SQL or ambiguous column references, so the helper throws immediately with this message.","triggerScenarios":"Calling storage query/filter helpers (callers: `column`, `resolveDistinctColumnSql`, `buildJsonPath`, `sanitizeColumn`, `field`) with an empty string — e.g. from a destructured config where a column name was never set, `record[field]` with undefined field, or `''` passed by default.","commonSituations":"Dynamic column lists built from optional user selection where an unset option yields `''`; template literal `select(${prefix}.${col})` with empty col; JSON key paths joined from empty metadata keys.","solutions":["Check the key before calling: `if (!key) throw new Error('column name required')` at the call site or default it to a valid column.","Filter falsy entries from dynamically built column arrays before passing them to storage APIs.","Trace where the empty string originates — usually an unset option or empty object key from user input."],"exampleFix":"// before\nconst cols = [input.sortBy, 'created_at']; // sortBy may be ''\n// after\nconst cols = [input.sortBy || 'created_at', 'created_at'].filter(Boolean);","handlingStrategy":"validation","validationCode":"function assertFieldKey(key: string) {\n  if (!key) throw new Error('Field key cannot be empty');\n  if (!key.split('.').every(s => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s) && s.length <= 63))\n    throw new Error(`Invalid field key: ${key}`);\n}","typeGuard":"function isNonEmptyFieldKey(k: string | undefined | null): k is string {\n  return typeof k === 'string' && k.length > 0;\n}","tryCatchPattern":"let col: FieldKey;\ntry {\n  col = parseFieldKey(selectedColumn);\n} catch (e) {\n  throw new Error(`Column selection failed: ${(e as Error).message}`);\n}","preventionTips":["Default optional column options before use (`input.sortBy || 'created_at'`) instead of passing ''.","Filter falsy values out of dynamically built column arrays.","Validate user-supplied field selections at the API boundary before they reach storage code."],"tags":["sql","validation","field-key","storage"],"backgroundTag":"invalid-field-key","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}