Stagehand + zod 4: Invalid schema for response_format, type None

TL;DR

For "BadRequestError: 400 Invalid schema for responseformat 'operatorResponseSchema': schema must be a JSON Schema of 'type: "object"', got 'typ": with Stagehand 2.4.3 and zod 4.0.17 installed, importing and using Stagehand throws BadRequestError: 400 Invalid schema for response\format 'operatorResponseSchema': schema must be a JSON Schema of 'type: "object"', got 'type: "None"'.

BadRequestError: 400 Invalid schema for response_format 'operatorResponseSchema': schema must be a JSON Schema of 'type: "object"', got 'type: "None"'

Steps

1. With Stagehand 2.4.3 and zod 4.0.17 installed, importing and using Stagehand throws BadRequestError: 400 Invalid schema for response_format 'operatorResponseSchema': schema must be a JSON Schema of 'type: "object"', got 'type: "None"'. Pinning zod to 3.25.76 makes the errors disappear, even though Stagehand's peer range declares >=3.25.0 <4.1.0.
2. Stagehand's published types imported zod/v3 internals, so a v4 install silently produced type: "None" schemas that the model provider rejects. The team's fix was to pin zod to ^3.25.0 (PR #1032, released in 2.5.0) while they finished proper v4 support, which landed via commit f27a99c in later 2.5.x. If you hit this on 2.4.x/2.5.0, upgrade Stagehand past 2.5.0, or pin zod to ^3.25.0.

When to use

You are seeing this: Pinning zod to 3.25.76 makes the errors disappear, even though Stagehand's peer range declares >=3.25.0 <4.1.0. Use this skill when you run into "Stagehand + zod 4: Invalid schema for response_format, type None".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: Stagehand 2.4.3, zod 4.0.17, 3.25.76, gt 3.25.0, lt 4.1.0, 2.5.0. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Question asked in the thread: With Stagehand 2.4.3 and zod 4.0.17 installed, importing and using Stagehand throws BadRequestError: 400 Invalid schema for response_format 'operatorResponseSchema': schema must be a JSON Schema of 'type: "object"', got 'type: "None"'. Pinning zod to 3.25.76 makes the errors disappear, even though Stagehand's peer range declares >=3.25.0 <4.1.0.

Verified answer: Stagehand's published types imported zod/v3 internals, so a v4 install silently produced type: "None" schemas that the model provider rejects. The team's fix was to pin zod to ^3.25.0 (PR #1032, released in 2.5.0) while they finished proper v4 support, which landed via commit f27a99c in later 2.5.x. If you hit this on 2.4.x/2.5.0, upgrade Stagehand past 2.5.0, or pin zod to ^3.25.0.

Source: https://github.com/browserbase/stagehand/issues/1029

Thread: https://vectle.com/threads/thr_T72UXsEopphCClqga3FKTw