mastra-ai/mastra · error

Invalid field key segment: ${segment} in ${key}

Error message

Invalid field key segment: ${segment} in ${key}

What it means

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

Source

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

 *   - 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>;
}

/**
 * Selectively extracts specific fields from an object using dot notation.
 * Does not error if fields don't exist - simply omits them from the result.

View on GitHub (pinned to 75dd419e61)

Solutions

1. 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, '_')`.
2. 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.
3. Validate/sanitize user-derived metadata keys at ingestion time so they are field-key safe downstream.

Example fix

// before
buildJsonPath('user.first-name'); // hyphen rejected
// after
buildJsonPath('user.first_name');

function sanitizeFieldKey(key: string): string {
  return key.split('.').map(s => s.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 63)).join('.');
}
// sanitizeFieldKey('user.first-name') -> 'user.first_name'

function isValidFieldKey(key: string): boolean {
  return key.split('.').every(s => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s) && s.length <= 63);
}

let path: FieldKey;
try {
  path = parseFieldKey(metadataPath);
} catch (e) {
  path = parseFieldKey(sanitizeFieldKey(metadataPath));
}

When it happens

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

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

Related errors

• Field key cannot be empty
• Invalid ${kind}: ${name}. Must start with a letter or unders
• ClaudeSDKAgent resumeData must include sessionId or continue
• CursorSDKAgent resumeData must include a message.
• CursorSDKAgent resumeData.agentId must be a string when prov

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