{"id":"566e941a4df632f0","repo":"colinhacks/zod","slug":"synchronous-parse-encountered-promise","errorCode":null,"errorMessage":"Synchronous parse encountered promise.","messagePattern":"Synchronous parse encountered promise\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v3/types.ts","lineNumber":213,"sourceCode":"    return {\n      status: new ParseStatus(),\n      ctx: {\n        common: input.parent.common,\n        data: input.data,\n\n        parsedType: getParsedType(input.data),\n\n        schemaErrorMap: this._def.errorMap,\n        path: input.path,\n        parent: input.parent,\n      },\n    };\n  }\n\n  _parseSync(input: ParseInput): SyncParseReturnType<Output> {\n    const result = this._parse(input);\n    if (isAsync(result)) {\n      throw new Error(\"Synchronous parse encountered promise.\");\n    }\n    return result;\n  }\n\n  _parseAsync(input: ParseInput): AsyncParseReturnType<Output> {\n    const result = this._parse(input);\n    return Promise.resolve(result);\n  }\n\n  parse(data: unknown, params?: util.InexactPartial<ParseParams>): Output {\n    const result = this.safeParse(data, params);\n    if (result.success) return result.data;\n    throw result.error;\n  }\n\n  safeParse(data: unknown, params?: util.InexactPartial<ParseParams>): SafeParseReturnType<Input, Output> {\n    const ctx: ParseContext = {\n      common: {","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/colinhacks/zod/blob/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v3/types.ts#L195-L231","documentation":"Thrown by _parseSync when the underlying _parse returns a value flagged as async (a Promise). Synchronous parse paths (`.parse`, `.safeParse`, `.spa` only when awaited-but-sync) cannot await, so zod refuses rather than silently returning `[object Promise]`.","triggerScenarios":"Using `.parse()` / `.safeParse()` (sync) on a schema that contains an async refinement (`.refine(async ...)`) or async transform (`.transform(async ...)`), or a schema that nests one.","commonSituations":"Adding an async validation (e.g. database uniqueness check) to an existing sync pipeline; refactoring a transform to be async without flipping the call site; testing an async schema with a sync assertion.","solutions":["Switch the call site to the async API: `.parseAsync(data)` or `.spa(data)` (returns a Promise).","If you must stay sync, remove the async refinement/transform or replace it with a sync check.","Audit nested schemas — the async schema may be a field inside an object or array."],"exampleFix":"// before\nconst schema = z.string().refine(async (v) => await checkDb(v));\nschema.parse(value); // throws \"Synchronous parse encountered promise.\"\n\n// after\nawait schema.parseAsync(value);\n// or\nconst res = await schema.spa(value);","handlingStrategy":"validation","validationCode":"// Detect async schemas before calling sync parse\nfunction isAsyncSchema(s: z.ZodTypeAny): boolean {\n  // heuristic: walk _def for ZodEffects with async transform/refine\n  return /\\[z\\.async\\]|Promise/.test(s.description ?? \"\") || (s as any)._def?.effect != null;\n}","typeGuard":"function canParseSync(s: z.ZodTypeAny): boolean {\n  // No public flag; safest is to always use parseAsync for schemas that may contain effects.\n  return true;\n}","tryCatchPattern":"try { schema.parse(data); }\ncatch (e) {\n  if (e instanceof Error && /encountered promise|Use \\.parseAsync/.test(e.message)) {\n    return await schema.parseAsync(data);\n  }\n  throw e;\n}","preventionTips":["Default to parseAsync/spa whenever a schema uses .refine/.transform with possibly-async callbacks.","Audit refinements and transforms for `async` keyword before using .parse.","Keep validation pipelines uniform: pick sync or async per schema and document it."],"tags":["async","parse","v3"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}