Bug: Zod schema Cognito Trigger Event `preferredRole` property may be `null`

[bdellegrazie]

Expected Behavior

The event parses successfully.

Current Behavior

In the initial request event being sent from Cognito for the pre token generation trigger lambda, the preferredRole and claimsAndScopeOverrideDetails values may be null causing the parser to fail validation.

Example:

{
    "version": "2",
    "triggerSource": "TokenGeneration_Authentication",
    "region": "eu-west-2",
    "userPoolId": "eu-west-2_POOL_ID",
    "userName": "fakeUsername",
    "callerContext": {
        "awsSdkVersion": "aws-sdk-unknown-unknown",
        "clientId": "fake-client-id"
    },
    "request": {
        "userAttributes": {
            "sub": "0720b425-7607-41f2-b476-b03dd6a3c167",
            "cognito:email_alias": "fake.username@example.com",
            "cognito:user_status": "CONFIRMED",
            "email_verified": "true",
            "name": "Fake Username",
            "phone_number_verified": "true",
            "cognito:phone_number_alias": "+15555555555",
            "phone_number": "+15555555555",
            "family_name": "Username",
            "email": "fake.username@example.com"
        },
        "groupConfiguration": {
            "groupsToOverride": [
                "example-group"
            ],
            "iamRolesToOverride": [],
            "preferredRole": null
        },
        "scopes": [
            "aws.cognito.signin.user.admin"
        ]
    },
    "response": {
        "claimsAndScopeOverrideDetails": null
    }
}

Code snippet

import type {
  Context,
  PreTokenGenerationV2TriggerEvent,
} from "aws-lambda";
import type { LambdaInterface } from "@aws-lambda-powertools/commons/types";
import { parser } from "@aws-lambda-powertools/parser";
import {  PreTokenGenerationTriggerSchemaV2AndV3 } from "@aws-lambda-powertools/parser/schemas";

class Lambda implements LambdaInterface {
  @parser({ schema: PreTokenGenerationTriggerSchemaV2AndV3 })
  async handlerV2(
    event: PreTokenGenerationV2TriggerEvent,
    _context: Context,
  ): Promise<PreTokenGenerationV2TriggerEvent> {
    return event;
}

Steps to Reproduce

1. Create a test using the fake event above
2. Supply it to the empty event handler.

Possible Solution

1. Modify the schemas for the CognitoTriggerBaseSchema as follows:

change response type from z.object({}) to z.looseObject({}) - this isn't critical as z.object({}) will strip all keys.

const CognitoTriggerBaseSchema = z.object({
  version: z.string(),
  triggerSource: z.string(),
  region: z.string(),
  userPoolId: z.string(),
  userName: z.string().optional(),
  callerContext: z.object({
    awsSdkVersion: z.string(),
    clientId: z.string(),
  }),
  request: z.object({}),
  response: z.object({}),
});

2. Modify the PreTokenGenerationTriggerGroupConfigurationSchema to allow preferredRole to be null as follows:

change preferredRole type from z.string().optional() to z.string().nullish()

const PreTokenGenerationTriggerGroupConfigurationSchema = z.object({
  groupsToOverride: z.array(z.string()),
  iamRolesToOverride: z.array(z.string()),
  preferredRole: z.nullish(z.string()),
});

Powertools for AWS Lambda (TypeScript) version

latest

AWS Lambda function runtime

22.x

Packaging format used

npm

Execution logs

2025-08-01T15:59:10.464Z	0e1aa399-60b0-4d4b-96a8-11b480c7b536	ERROR	Invoke Error 	
{
    "errorType": "ParseError",
    "errorMessage": "Failed to parse schema",
    "name": "ParseError",
    "stack": [
        "ParseError: Failed to parse schema",
        "    at as (/var/task/dist/index.js:3:18209)",
        "    at o.value (/var/task/dist/index.js:3:18471)",
        "    at t.value (/var/task/dist/index.js:3:8914)",
        "    at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1205:29)"
    ]
}

[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 @bdellegrazie thank you for opening the issue and reporting the bug.

I deployed a Cognito User pool and tested the PreTokenGenerationTriggerSchemaV2AndV3 schema, and I was able to partly reproduce the behavior you described.

Specifically, the schema for the preferredRole field is indeed wrong and should be changed from z.string().optional() to z.string().nullable(). As far as I can tell the two values are either a string or null, so .nullable() here is a better option.

Regarding the claimsAndScopeOverrideDetails field, instead I was not able to reproduce the issue and once the fix above is applied, the schema works with claimsAndScopeOverrideDetails: null. This is expected because the current schema is defined as z.object({}) which is essentially an object with any content.

You can try defining a simple schema like:

z.object({
  response: z.object({}),
});

and parsing this object:

{
    response: {
        claimsAndScopeOverrideDetails: null
    }
}

and you'll see that the parsing is successful - for example using this Zod playground:

---

To recap, the bug is partially valid and to fix it, we should update the preferredRole field here to z.string().nullable().

Would you like to submit a pull request to fix it? If not, we'll try to address it before the next release.

[bdellegrazie]

@dreamorosi
Thanks for the feedback. Agree that the claimsAndScopeOverrideDetails is swallowed by the existing schema.
Happy to do a PR.