{"record":{"id":"fef3ed001efd6eb4","repo":"colinhacks/zod","slug":"asynchronous-transform-encountered-during-synchron","errorCode":null,"errorMessage":"Asynchronous transform encountered during synchronous parse operation. Use .parseAsync instead.","messagePattern":"Asynchronous transform encountered during synchronous parse operation\\. Use \\.parseAsync instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v3/types.ts","lineNumber":4421,"sourceCode":"            return { status: status.value, value: inner.value };\n          });\n        });\n      }\n    }\n\n    if (effect.type === \"transform\") {\n      if (ctx.common.async === false) {\n        const base = this._def.schema._parseSync({\n          data: ctx.data,\n          path: ctx.path,\n          parent: ctx,\n        });\n\n        if (!isValid(base)) return INVALID;\n\n        const result = effect.transform(base.value, checkCtx);\n        if (result instanceof Promise) {\n          throw new Error(\n            `Asynchronous transform encountered during synchronous parse operation. Use .parseAsync instead.`\n          );\n        }\n\n        return { status: status.value, value: result };\n      } else {\n        return this._def.schema._parseAsync({ data: ctx.data, path: ctx.path, parent: ctx }).then((base) => {\n          if (!isValid(base)) return INVALID;\n\n          return Promise.resolve(effect.transform(base.value, checkCtx)).then((result) => ({\n            status: status.value,\n            value: result,\n          }));\n        });\n      }\n    }\n\n    util.assertNever(effect);","sourceCodeStart":4403,"sourceCodeEnd":4439,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v3/types.ts#L4403-L4439","documentation":"Thrown at packages/zod/src/v3/types.ts:4421 during a synchronous parse when a transform's return value is a Promise. In the sync branch of the transform effect, Zod checks `if (result instanceof Promise)` and throws, because it cannot await the result inline. The message points to the remedy: use .parseAsync().","triggerScenarios":"Defining `z.string().transform(async (v) => await fetchDetails(v))` and parsing through `.parse()` or `.safeParse()` (sync). The transform returns a Promise, triggering the guard.","commonSituations":"Writing a transform that does I/O (fetch, DB, file read) and forgetting that transforms default to the sync parse path; converting a preprocess/transform pipeline to async without updating callers; library code that calls .parse() on user schemas that may contain async transforms.","solutions":["Move the call site to `await schema.parseAsync(data)` / `await schema.safeParseAsync(data)`.","If the call site must stay sync, replace the async transform with a synchronous one (do the I/O before parse, pass the result in).","Restructure so the async work happens outside the schema and the transform only reshapes already-fetched data synchronously.","Audit every .transform() on the schema for a returned Promise."],"exampleFix":"// before\nconst schema = z\n  .string()\n  .transform(async (id) => await db.find(id));\nschema.parse(input); // throws: Asynchronous transform encountered...\n\n// after\nawait schema.parseAsync(input);","handlingStrategy":"validation","validationCode":"import { ZodType, ZodFirstPartyTypeKind } from 'zod';\n\nfunction findAsyncTransforms(schema: ZodType, path: string[] = []): string[] {\n  const def = (schema as any)._def;\n  if (!def) return [];\n  if (def.typeName === ZodFirstPartyTypeKind.ZodEffects && def.effect?.type === 'transform') {\n    const src = def.effect.transform?.toString() ?? '';\n    if (/\\basync\\b/.test(src)) return [path.join('.') || '(root)'];\n    return findAsyncTransforms(def.schema, path);\n  }\n  return [];\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Switch callers to .parseAsync()/.safeParseAsync() whenever a transform returns a Promise.","Do I/O before parse and let the transform only reshape already-fetched data synchronously.","Grep for `.transform(async` when introducing async work in a schema pipeline.","Document which exported schemas are async-only."],"tags":["async","transform","parse","sync","effects"],"backgroundTag":null,"analyzedSha":"2d90846af918af9602e088812d63a035d47cdbe4","analyzedAt":"2026-08-11T01:21:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}