Optional text Argument Not Received in Query Handler

[atsuki-sakai]

When invoking the Convex API query with an optional argument text, the query handler only receives the clerkId and the text property is missing (i.e., it is undefined). This happens even though the client code explicitly passes text as a string.

Steps to Reproduce:

// api/webhook 
const salon = await fetchQuery(api.salon.core.getClerkId, {
  clerkId: id,
  text: 'hello world' as string,
});

Convex API Definition:

// convex/salon/core.ts
export const getClerkId = query({
  args: {
    clerkId: v.string(),
    text: v.optional(v.string()),
    test: v.optional(v.number()),
  },
  handler: async (ctx, args) => {
    console.log('JSON args:', JSON.stringify(args));
    console.log('Object args', Object.keys(args));
    console.log('text:', typeof args.text);
    console.log('test:', typeof args.test);
    authCheck(ctx, args.text!);
    validateSalon(args);
    // 指定されたClerk IDを持つサロンを検索
    return await ctx.db
      .query('salon')
      .withIndex('by_clerk_id', (q) => q.eq('clerkId', args.clerkId).eq('isArchive', false))
      .first();
  },
});

Log Output:

2025/3/31 6:39:08 [CONVEX Q(salon/core:getClerkId)] [LOG] 'JSON args:' '{"clerkId":"user_2uo1SE######################"}'
2025/3/31 6:39:08 [CONVEX Q(salon/core:getClerkId)] [LOG] 'Object args' [ 'clerkId' ]
2025/3/31 6:39:08 [CONVEX Q(salon/core:getClerkId)] [LOG] 'text:' 'undefined'
2025/3/31 6:39:08 [CONVEX Q(salon/core:getClerkId)] [LOG] 'test:' 'undefined'

Expected Behavior:

The query handler should receive the following arguments:
• clerkId: with the passed string value.
• text: with the string value 'hello world'.

Instead, the serialized arguments only contain clerkId and omit text, resulting in args.text being undefined.

Environment:
• Convex API Version: "convex": "^1.17.4",
• Client/Server Environment: "next": "15.1.3",

Additional Notes:
• The client code uses as string for text, but note that this is only a compile-time assertion and does not affect runtime behavior.
• The issue might be related to how Convex handles optional arguments during serialization or validation.
• Similar issues have not been observed with other required parameters.

Impact:

This bug affects the ability to pass optional parameters to the query handler, which may lead to unexpected behavior or failures in application logic that relies on these parameters.

Request for Assistance:

Please investigate whether this is a bug in the Convex API’s argument handling or if there is a misconfiguration in the query schema. Any insights or fixes would be greatly appreciated.

⸻

This issue report should provide enough context for the development team to understand and reproduce the problem.

https://github.com/atsuki-sakai/bcker-project/tree/develop