{"record":{"id":"dea2532f44afd7dc","repo":"colinhacks/zod","slug":"unrecognized-key-key","errorCode":null,"errorMessage":"Unrecognized key: \"${key}\"","messagePattern":"Unrecognized key: \"(.+?)\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v4/core/util.ts","lineNumber":615,"sourceCode":"  int64: [/* @__PURE__*/ BigInt(\"-9223372036854775808\"), /* @__PURE__*/ BigInt(\"9223372036854775807\")],\n  uint64: [/* @__PURE__*/ BigInt(0), /* @__PURE__*/ BigInt(\"18446744073709551615\")],\n};\n\nexport function pick(schema: schemas.$ZodObject, mask: Record<string, unknown>): any {\n  const currDef = schema._zod.def;\n\n  const checks = currDef.checks;\n  const hasChecks = checks && checks.length > 0;\n  if (hasChecks) {\n    throw new Error(\".pick() cannot be used on object schemas containing refinements\");\n  }\n\n  const def = mergeDefs(schema._zod.def, {\n    get shape() {\n      const newShape: Writeable<schemas.$ZodShape> = {};\n      for (const key in mask) {\n        if (!(key in currDef.shape)) {\n          throw new Error(`Unrecognized key: \"${key}\"`);\n        }\n        if (!mask[key]) continue;\n        newShape[key] = currDef.shape[key]!;\n      }\n\n      assignProp(this, \"shape\", newShape); // self-caching\n      return newShape;\n    },\n    checks: [],\n  });\n\n  return clone(schema, def) as any;\n}\n\nexport function omit(schema: schemas.$ZodObject, mask: object): any {\n  const currDef = schema._zod.def;\n\n  const checks = currDef.checks;","sourceCodeStart":597,"sourceCodeEnd":633,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/util.ts#L597-L633","documentation":"Thrown by the pick() helper when iterating the supplied mask: every key in the mask must already exist in the object schema's shape. The mask is treated as a closed allow-list, so a typo'd or stale key is rejected rather than silently ignored. This surfaces at `.pick()` call time inside the lazy shape getter.","triggerScenarios":"Calling `schema.pick({ nmae: true })` where `nmae` is not a defined field; passing a mask built from an older version of the schema after a rename; generating the mask from a union of field names that includes keys not present on this particular object.","commonSituations":"Typos in the mask literal; copy-pasting a mask from a sibling schema; refactoring a field name without updating every `.pick()` site; programmatic mask construction from user input or config.","solutions":["Check the error message for the exact offending key and correct the mask to match the schema's defined fields.","If building the mask dynamically, filter candidate keys against `Object.keys(schema._zod.def.shape)` (or the inferred keys) before calling `.pick()`.","Update renamed fields across all `.pick()` call sites during a refactor."],"exampleFix":"// before\nconst S = z.object({ id: z.string(), name: z.string() });\nS.pick({ nmae: true }); // throws: Unrecognized key \"nmae\"\n\n// after\nS.pick({ name: true });","handlingStrategy":"validation","validationCode":"function buildPickMask<T extends z.ZodObject>(schema: T, want: string[]): Record<string, true> {\n  const known = new Set(Object.keys((schema as any)._zod.def.shape));\n  const mask: Record<string, true> = {};\n  for (const k of want) {\n    if (!known.has(k)) throw new TypeError(`Unrecognized key for pick(): ${String(k)}`);\n    mask[k] = true;\n  }\n  return mask;\n}\n// schema.pick(buildPickMask(schema, ['a', 'b']));","typeGuard":"function isKnownKey(schema: z.ZodObject, key: PropertyKey): boolean {\n  return Object.prototype.hasOwnProperty.call((schema as any)._zod.def.shape, key);\n}","tryCatchPattern":null,"preventionTips":["Derive masks from the schema's own keys, not from hand-typed literals, in dynamic code.","During field renames, grep for `.pick({` and `.omit({` sites and update them together.","Treat the mask as an allow-list that must match the schema's vocabulary exactly."],"tags":["schema-transformation","pick","typo","object-schema","zod-v4"],"backgroundTag":null,"analyzedSha":"2d90846af918af9602e088812d63a035d47cdbe4","analyzedAt":"2026-08-11T01:21:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}