{"record":{"id":"8a5a9bdd6672a2f4","repo":"mastra-ai/mastra","slug":"cannot-flatten-intersections-with-overlapping-keys","errorCode":null,"errorMessage":"Cannot flatten intersections with overlapping keys","messagePattern":"Cannot flatten intersections with overlapping keys","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/schema-compat/src/schema-compatibility-v4.ts","lineNumber":730,"sourceCode":"    }\n    return [value];\n  }\n\n  /**\n   * Default handler for Zod intersection types.\n   * Flattens the intersection tree and merges object shapes into a single z.object().\n   * Falls back to z.any() for non-object intersections.\n   */\n  public defaultZodIntersectionHandler(value: ZodIntersection<any, any>): ZodType {\n    const leaves = this.collectIntersectionLeaves(value);\n    const processed = leaves.map(leaf => this.processZodType(leaf));\n\n    if (processed.every(p => p instanceof ZodObject)) {\n      const mergedShape: Record<string, ZodType> = {};\n      for (const obj of processed as ZodObject<any, any>[]) {\n        for (const [key, field] of Object.entries(obj.shape)) {\n          if (key in mergedShape) {\n            throw new Error('Cannot flatten intersections with overlapping keys');\n          }\n          mergedShape[key] = field as ZodType;\n        }\n      }\n      let result: ZodType = z.object(mergedShape);\n      if (value.description) {\n        result = result.describe(value.description);\n      }\n      return result;\n    }\n\n    return z.any().describe(value.description || 'intersection type');\n  }\n\n  /**\n   * Processes a Zod object schema and converts it to an AI SDK Schema.\n   *\n   * @param zodSchema - The Zod object schema to process","sourceCodeStart":712,"sourceCodeEnd":748,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/schema-compat/src/schema-compatibility-v4.ts#L712-L748","documentation":"defaultZodIntersectionHandler flattens z.intersection of two ZodObjects into a single object with a merged shape when all processed members are objects. Because a true intersection can allow conflicting field types, this library refuses to merge when the same key appears in both sides, throwing instead of silently picking one type.","triggerScenarios":"Calling the Zod v4 schema compatibility layer with `z.intersection(z.object({ id: z.string() }), z.object({ id: z.number(), ... }))` or any two object schemas sharing at least one key.","commonSituations":"Combining base schemas with extension schemas (e.g. base + mixins) that both define `id`, `metadata`, or timestamps; spreading a common schema into domain schemas and then intersecting them; migrations from deepPartial/merge patterns.","solutions":["Rename the overlapping key on one side so the shapes are disjoint.","Use z.object({ ...a.shape, ...b.shape }) manually with an explicit resolution for the shared key (e.g. omit it from one side via .omit()).","Replace z.intersection with a single schema containing all required fields.","Use z.union of the two objects if the value is really one shape OR the other, not both."],"exampleFix":"// before\nconst schema = z.intersection(z.object({ id: z.string() }), z.object({ id: z.number() }));\n// after\nconst schema = z.object({ id: z.string() }).extend({ score: z.number() });","handlingStrategy":"validation","validationCode":"function assertDisjointShapes(a: z.ZodObject<any>, b: z.ZodObject<any>) {\n  const overlap = Object.keys(a.shape).filter(k => k in b.shape);\n  if (overlap.length) throw new TypeError(`Intersection keys overlap: ${overlap.join(', ')}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  processed = compat.process(schema);\n} catch (e) {\n  if ((e as Error).message.includes('overlapping keys')) {\n    throw new Error('Restructure: use object merge with explicit key resolution instead of z.intersection', { cause: e });\n  }\n  throw e;\n}","preventionTips":["Prefer z.object({ ...a.shape, ...b.shape }) merges with explicit conflict handling.","Name base/mixin keys distinctly to avoid collisions.","Assert shape disjointness when composing schemas in tests."],"tags":["zod","zod-v4","intersection"],"backgroundTag":"overlapping-schema-keys","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}