What causes "Field key cannot be empty" in mastra-ai/mastra?

Check the key before calling: `if (!key) throw new Error('column name required')` at the call site or default it to a valid column.

mastra-ai/mastra · error

Field key cannot be empty

Error message

Field key cannot be empty

What it means

`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.

Source

Thrown at packages/core/src/utils.ts:619

/**
 * Parses and returns a valid dot-separated SQL field key (e.g., 'user.profile.name').
 * Each segment must:
 *   - Start with a letter (a-z, A-Z) or underscore (_)
 *   - Contain only letters, numbers, or underscores
 *   - Be at most 63 characters long
 *
 * @param key - The dot-separated field key string to parse.
 * @returns The validated field key as a branded type.
 * @throws {Error} If any segment of the key is invalid.
 *
 * @example
 * const key = parseFieldKey('user_profile.name'); // Ok
 * parseFieldKey('user..name'); // Throws error
 * parseFieldKey('user.123name'); // Throws error
 */
export function parseFieldKey(key: string): FieldKey {
  if (!key) throw new Error('Field key cannot be empty');
  const segments = key.split('.');
  for (const segment of segments) {
    if (!SQL_IDENTIFIER_PATTERN.test(segment) || segment.length > 63) {
      throw new Error(`Invalid field key segment: ${segment} in ${key}`);
    }
  }
  return key as FieldKey;
}

/**
 * Removes specific keys from an object.
 * @param obj - The original object
 * @param keysToOmit - Keys to exclude from the returned object
 * @returns A new object with the specified keys removed
 */
export function omitKeys<T extends Record<string, any>>(obj: T, keysToOmit: string[]): Partial<T> {
  return Object.fromEntries(Object.entries(obj).filter(([key]) => !keysToOmit.includes(key))) as Partial<T>;
}

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
const cols = [input.sortBy, 'created_at']; // sortBy may be ''
// after
const cols = [input.sortBy || 'created_at', 'created_at'].filter(Boolean);

Defensive patterns

Strategy: validation

Validate before calling

function assertFieldKey(key: string) {
  if (!key) throw new Error('Field key cannot be empty');
  if (!key.split('.').every(s => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s) && s.length <= 63))
    throw new Error(`Invalid field key: ${key}`);
}

Type guard

function isNonEmptyFieldKey(k: string | undefined | null): k is string {
  return typeof k === 'string' && k.length > 0;
}

Try / catch

let col: FieldKey;
try {
  col = parseFieldKey(selectedColumn);
} catch (e) {
  throw new Error(`Column selection failed: ${(e as Error).message}`);
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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