Recursive schema with lazy() doesn't seem to work

[dearlordylord]

reproduction https://github.com/dearlordylord/zod-recursive-problem

similar problems exist #3560 , #3331

but they seem to yield different errors and have different reasons

Context

I have a file system-like structure where a node is a discriminated union of a leaf (file) or a node with n leaves (directory)

(the type signature goes further in the code example and in the repo )

I tried another parser library https://github.com/effect-ts/effect/tree/main/packages/schema and can pull it off with both compile time and runtime

however, Zod doesn't seem to compile this correctly, but it does run and validate correctly runtime:

(the same code is in counter.tsx of https://github.com/dearlordylord/zod-recursive-problem )

import { z } from 'zod';

type FileSystem = (
  | {
  readonly type: 'directory';
  readonly children: readonly FileSystem[];
}
  | {
  readonly type: 'file';
}
  ) & {
  readonly name: FileSystemName;
};

const fileSystemNameSchema = z.string().min(1).max(255).brand('fileSystemName');
type FileSystemName = z.infer<typeof fileSystemNameSchema>;

const fileSystemBaseSchema = z.object({
  name: fileSystemNameSchema
});

const fileSystemDirectoryBaseSchema = fileSystemBaseSchema.extend({
  type: z.literal('directory')
});

type FileSystemDirectory = z.infer<typeof fileSystemDirectoryBaseSchema> & {
  readonly children: readonly FileSystem[];
}

const fileSystemDirectorySchema: z.ZodType<FileSystemDirectory> = fileSystemDirectoryBaseSchema.extend({
  children: z.lazy(() => z.array(fileSystemSchema))
});

const fileSystemFileSchema = fileSystemBaseSchema.extend({
  type: z.literal('file')
});

export const fileSystemSchema = z.discriminatedUnion('type', [
  fileSystemDirectorySchema,
  fileSystemFileSchema
]);

the error is

src/counter.ts:30:7 - error TS2322: Type 'ZodObject<extendShape<extendShape<{ name: ZodBranded<ZodString, "fileSystemName">; }, { type: ZodLiteral<"directory">; }>, { children: ZodLazy<ZodArray<ZodDiscriminatedUnion<"type", [...]>, "many">>; }>, "strip", ZodTypeAny, { ...; }, { ...; }>' is not assignable to type 'ZodType<FileSystemDirectory, ZodTypeDef, FileSystemDirectory>'.
  Types of property '_type' are incompatible.
    Type '{ type: "directory"; name: string & BRAND<"fileSystemName">; children: { [x: string]: any; type?: unknown; }[]; }' is not assignable to type 'FileSystemDirectory'.
      Type '{ type: "directory"; name: string & BRAND<"fileSystemName">; children: { [x: string]: any; type?: unknown; }[]; }' is not assignable to type '{ readonly children: readonly FileSystem[]; }'.
        Types of property 'children' are incompatible.
          Type '{ [x: string]: any; type?: unknown; }[]' is not assignable to type 'readonly FileSystem[]'.
            Type '{ [x: string]: any; type?: unknown; }' is not assignable to type 'FileSystem'.
              Type '{ [x: string]: any; type?: unknown; }' is not assignable to type '{ readonly type: "directory"; readonly children: readonly FileSystem[]; } & { readonly name: string & BRAND<"fileSystemName">; }'.
                Property 'children' is missing in type '{ [x: string]: any; type?: unknown; }' but required in type '{ readonly type: "directory"; readonly children: readonly FileSystem[]; }'.

zod ^3.23.8

[martijnarts]

Looks like it might be the same problem as here: #3628

This resolution worked for me there: #1500 (comment)

[dosubot]

Hi, @dearlordylord. I'm Dosu, and I'm helping the Zod team manage their backlog. I'm marking this issue as stale.

Issue Summary:

• You reported a TypeScript compilation error when using Zod's lazy() function for a recursive schema.
• The schema validates correctly at runtime but fails to compile.
• @martijnarts suggested a potential resolution related to a known issue, providing a link that might solve the TypeScript error.

Next Steps:

• Please let us know if this issue is still relevant with the latest version of Zod. If so, you can keep the discussion open by commenting here.
• Otherwise, this issue will be automatically closed in 7 days.

Thank you for your understanding and contribution!

[dosubot]

Hi @dearlordylord! I'm Dosu and I’m helping the zod team.

I'm a bot trained on Zod's codebase and issues.

The TypeScript error you're seeing is a well-known result of TypeScript's limitations with recursive types, especially when combined with discriminated unions and branded types. Zod's z.lazy() is the correct approach for recursive schemas, and runtime validation works as expected, but TypeScript often can't infer the precise static type for recursive discriminated unions—so you get type errors or unknown[] in the inferred types. This is an intentional tradeoff in Zod, prioritizing runtime validation reliability over strict static type inference for these advanced cases [source].

Workarounds include using explicit type annotations on recursive properties/getters, or splitting schemas into non-recursive and recursive parts. For example, you can define the recursive property as a getter with an explicit return type, or use a type assertion on the schema definition [source].

Zod 4 has improved cyclical inference for z.object(), but recursive inference in unions/discriminatedUnions still requires these workarounds [source]. The Zod docs and several issues discuss these patterns in more detail:

• Recursive objects
• Circularity errors
• Workarounds and discussion

If you want a concrete workaround, try wrapping the recursive discriminated union in z.lazy(() => ...) everywhere it's referenced recursively, or use an explicit type annotation on the recursive property. This should resolve the TypeScript error, though it may require some manual type assertions.

If this answers your question, please close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}