Unannounced breaking changes: v2.24.1 zod peer dependency

[niklash3]

Expected Behavior

Hi!

In commit 7a65fcf9759ac1a1f072ef5442ee8b0767705a92 (version 2.24.1) you bumped the zod peer dependency from v3 to v4, which is considered a breaking change according to semver.

This leads to downstream libraries which are still using zod 3 to experience NPM install failures such as the following:

npm error While resolving: @aws-lambda-powertools/parser@2.25.1
npm error Found: zod@3.25.76
npm error node_modules/zod
npm error   zod@"^3.25.42" from the root project
npm error
npm error Could not resolve dependency:
npm error peerOptional zod@"4.x" from @aws-lambda-powertools/parser@2.25.1
npm error node_modules/@aws-lambda-powertools/parser
npm error   @aws-lambda-powertools/parser@"^2.20.0" from the root project
npm error
npm error Conflicting peer dependency: zod@4.1.1
npm error node_modules/zod
npm error   peerOptional zod@"4.x" from @aws-lambda-powertools/parser@2.25.1
npm error   node_modules/@aws-lambda-powertools/parser
npm error     @aws-lambda-powertools/parser@"^2.20.0" from the root project

I guess this is unactionable now unless you want to yank all versions since 2.24.1 and release a new major version... However, do keep this in mind for future peer dependency updates.

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #typescript channel on our Powertools for AWS Lambda Discord: Invite link

[dreamorosi]

Hi @niklash3, thank you for opening this issue.

I understand this is causing friction for your workload, which is never ideal. For transparency on our decision process:

Before making this change, when Zod started publishing v4 alongside v3 in May we opened a request for comments issue to gather feedback from our customer base regarding the update. In this issue we communicated that we wouldn't cut a major release on our side if we were to upgrade to Zod v4.

We left the issue open for 2 months and communicated via social media and our Discord Server. During this period, several customers requested we move forward with the update, and nobody expressed a need to keep supporting v3. Some even mentioned the lack of Zod v4 support was blocking their ability to adopt our library since their codebases were already using it.

This decision aligns with our documented versioning policy which states:

AWS reserves the right to stop support for an underlying dependency without increasing the major SDK version

When we made the release, we highlighted this change at the top of the release notes (second line).

For your immediate needs, sticking to a version before v2.24.1 until you're ready to migrate to Zod v4 would be the most straightforward solution, given that besides Zod v4 support not much has changed in Parser since then.

We appreciate you bringing this to our attention as it helps us understand the impact of our decisions in the future.

[powertools-for-aws-oss-automation]

Warning

This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.