{"record":{"id":"f7b87486aa94bc94","repo":"colinhacks/zod","slug":"partial-cannot-be-used-on-object-schemas-contai","errorCode":null,"errorMessage":".partial() cannot be used on object schemas containing refinements","messagePattern":"\\.partial\\(\\) cannot be used on object schemas containing refinements","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v4/core/util.ts","lineNumber":729,"sourceCode":"    get catchall() {\n      return b._zod.def.catchall;\n    },\n    checks: b._zod.def.checks ?? [],\n  });\n\n  return clone(a, def) as any;\n}\n\nexport function partial(\n  Class: SchemaClass<schemas.$ZodOptional> | null,\n  schema: schemas.$ZodObject,\n  mask: object | undefined\n): any {\n  const currDef = schema._zod.def;\n  const checks = currDef.checks;\n  const hasChecks = checks && checks.length > 0;\n  if (hasChecks) {\n    throw new Error(\".partial() cannot be used on object schemas containing refinements\");\n  }\n\n  const def = mergeDefs(schema._zod.def, {\n    get shape() {\n      const oldShape = schema._zod.def.shape;\n      const shape: Writeable<schemas.$ZodShape> = { ...oldShape };\n\n      if (mask) {\n        for (const key in mask) {\n          if (!(key in oldShape)) {\n            throw new Error(`Unrecognized key: \"${key}\"`);\n          }\n          if (!(mask as any)[key]) continue;\n          // if (oldShape[key]!._zod.optin === \"optional\") continue;\n          shape[key] = Class\n            ? new Class({\n                type: \"optional\",\n                innerType: oldShape[key]!,","sourceCodeStart":711,"sourceCodeEnd":747,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/util.ts#L711-L747","documentation":"Thrown by partial() when the source object has refinements. `.partial()` wraps selected (or all) fields in an optional wrapper and rebuilds the schema with an empty checks array, which would silently discard object-level refinements. Like `.pick()`/`.omit()`, the operation is blocked rather than losing the invariants.","triggerScenarios":"Calling `myObject.partial()` or `myObject.partial({ a: true })` on an object schema that has `.refine()`/`.check()` attached at the object node. Eager throw at `.partial()` call time.","commonSituations":"Building a PATCH/update schema from a full entity that carries cross-field invariants; making a form-input schema optional where the source has validation rules; layering `.partial()` over a schema that gained a refinement after a refactor.","solutions":["Apply `.partial()` to a refinement-free base, then re-apply the refinement to the result.","Build the partial schema from scratch with `z.object({ a: z.string().optional() })` and add only the refinements that still make sense.","Move the refinement to leaf fields so it survives the partial() rebuild."],"exampleFix":"// before\nconst S = z.object({ a: z.string(), b: z.string() }).refine(v => v.a !== v.b);\nconst P = S.partial(); // throws\n\n// after\nconst P = z.object({ a: z.string().optional(), b: z.string().optional() })\n  .refine(v => (v.a ?? '') !== (v.b ?? ''));","handlingStrategy":"validation","validationCode":"function canPartial(schema: z.ZodObject): boolean {\n  const checks = (schema as any)?._zod?.def?.checks;\n  return !checks || checks.length === 0;\n}\n// if (!canPartial(S)) { /* rebuild from a refinement-free base */ }","typeGuard":"function hasObjectRefinements(schema: z.ZodObject): boolean {\n  const checks = (schema as any)?._zod?.def?.checks;\n  return Array.isArray(checks) && checks.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Build PATCH/update schemas from a refinement-free base, then re-apply invariants.","Move cross-field invariants to leaf-level `.refine()` when you need both partial() and validation.","Centralize 'input vs entity' schema variants so refinements are not lost during transforms."],"tags":["schema-transformation","partial","refinement","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"}