Custom registries cannot support callbacks with schemas as arguments

[florianmartens]

Maybe I'm doing something wrong here but I'm trying to store a callback function in a metadata library but getting pretty nasty type errors. The error happens when the argument to my callback contains a ZodType.

Here's a minimal example:

import z, { ZodType } from "zod";

type Context = {
  schema: ZodType;
};

type MetadataObject = {
  a: string;
  b: "a" | "b";
};

export const registry = z.registry<
  MetadataObject | ((_validationContext: Context) => MetadataObject)
>();

function _text({ context, schema }: { context: Context; schema: ZodType }) {
  const found = registry.get(schema);
  const _metadata =
    found && typeof found === "function"
      ? found(context) // <- Error
      : found
        ? found
        : undefined;
}

Either it's something in my setup or drizzle has a problem resolving schema-based arguments to the correct type.

The type error:

Argument of type 'Context' is not assignable to parameter of type '{ schema: { def: { type: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "optional" | "nonoptional" | "nullable" | "default" | "prefault" | ... 26 more ... | "custom"; error?: ((issue: never) => string | ... 2 more ... | undefined) | undefined; checks?: { ...; }[] | unde...'.
The types of 'schema.def.checks' are incompatible between these types.
  Type '$ZodCheck<never>[] | undefined' is not assignable to type '{ _zod: { def: { check: string; error?: ((issue: never) => string | { message: string; } | null | undefined) | undefined; abort?: boolean | undefined; when?: ((payload: { value: unknown; issues: ({ [x: string]: unknown; ... 6 more ...; readonly continue?: boolean | undefined; } | ... 9 more ... | { ...; })[]; aborte...'.

Tested in zod 4.1.12

[dosubot]

This type error is caused by a mismatch between the expected parameter type of the callback function stored in your registry and the actual Context type you're passing in, specifically due to incompatibility in the internal structure of ZodType (like def.checks). TypeScript's structural typing means that even if two types look similar, differences in their internals—often due to multiple Zod instances or subtle type definition changes—can cause assignment errors. This is a common issue when using Zod schemas dynamically with generics or in monorepos with multiple Zod versions or instances see related issue.

Zod registries are designed to store strongly-typed metadata, and while you can technically store functions as metadata, the type system doesn't guarantee that your callback signatures will match up unless you tightly control the types involved docs. The registry implementation uses any for metadata to support dynamic patterns, including functions, but this flexibility comes at the cost of strict type safety discussion.

To work around this, you can use type assertions when retrieving and invoking your callback, or refactor your registry to more explicitly type the callback signatures. Also, ensure you are using a single Zod instance throughout your project to avoid type incompatibility issues see monorepo advice.

If you need more help, please share a fully runnable reproduction including your Zod version and any relevant context (like monorepo setup or how Zod is imported). If this solves your problem, feel free to close the issue!

To reply, just mention @dosu.

---

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

[florianmartens]

I don't think this is the correct answer in this case :( And: My project's zod version is pinned to 4.1.12 in all workspace projects.

[dosubot]

Thanks for your feedback—you're right, there's a deeper issue here. After digging into the Zod codebase and registry implementation, it turns out that storing callbacks in a registry where the argument type includes a ZodType (or an object containing one) leads to subtle TypeScript errors because of how Zod's internal $replace type recursively transforms metadata types. When you use a function signature like (_validationContext: Context) => MetadataObject in registry metadata, Zod's type machinery tries to structurally replace types inside Context, including the ZodType, which causes the resulting type to diverge from what you expect and leads to deep incompatibilities—especially around internal properties like def.checks on ZodType instances. This is not just a quirk of your setup; it's a side effect of how Zod's registry and type replacement logic work, and it's not directly supported or tested in the codebase.

There isn't a clean workaround except using type assertions or avoiding passing ZodType (or objects containing it) as arguments in registry-stored callbacks. If you need to store such callbacks, you may need to cast types at the call site or refactor your approach to avoid this pattern. This is a design tradeoff in Zod's registry system, and the docs/tests don't cover or encourage this usage pattern. If you want to see the relevant implementation details, check out the $replace utility and registry logic in the Zod source code (example).

If you have a more specific use case or a minimal reproduction, feel free to share it—happy to help dig deeper! If this clears things up, you can close the issue.

To reply, just mention @dosu.

---

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