{"record":{"id":"267bd4c32c9e370e","repo":"mastra-ai/mastra","slug":"invalid-parameters-for-strategy-strategy-err","errorCode":null,"errorMessage":"Invalid parameters for ${strategy} strategy: ${errorMessage}","messagePattern":"Invalid parameters for (.+?) strategy: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/document/validation.ts","lineNumber":142,"sourceCode":"  }\n\n  const result = schema.safeParse(params);\n  if (!result.success) {\n    // Extract unrecognized keys for cleaner error message\n    // Use 'issues' for Zod v4 compatibility (also available in Zod v3)\n    const issues = result.error.issues;\n    const unrecognizedError = issues.find((e: any) => e.code === 'unrecognized_keys');\n    if (unrecognizedError && 'keys' in unrecognizedError) {\n      const keys = (unrecognizedError as any).keys.join(', ');\n      throw new Error(`Invalid parameters for ${strategy} strategy: '${keys}' not supported`);\n    }\n\n    // Fallback to general error message for other validation issues\n    const errorMessage = issues\n      .map((e: any) => `${e.path.length > 0 ? e.path.join('.') : 'parameter'}: ${e.message}`)\n      .join(', ');\n\n    throw new Error(`Invalid parameters for ${strategy} strategy: ${errorMessage}`);\n  }\n}\n","sourceCodeStart":124,"sourceCodeEnd":145,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/document/validation.ts#L124-L145","documentation":"Fallback branch of validateChunkParams: when Zod validation fails but the issues are not 'unrecognized_keys' (i.e. real value problems), the issues are joined into a readable message and thrown. It reports things like wrong types, missing required fields, or values failing refinements for the given strategy's schema.","triggerScenarios":"Passing maxSize: '500' (string instead of number), negative overlap, missing required params for a strategy (e.g. missing dimension/group sizes), or values violating min/max constraints.","commonSituations":"Reading chunk options from env vars or query strings where everything is a string; JSON configs with nulls where numbers are required; passing overlap >= maxSize (though the transformer also guards that separately); forgetting required strategy-specific fields like separator or minLength.","solutions":["Read the joined message: each part is 'path: message' pointing at the offending parameter and Zod's reason.","Coerce types before calling: Number(env.maxSize) or z.coerce in your own config layer.","Supply all required parameters for the strategy per its exported options schema.","Ensure numeric constraints hold (positive sizes, overlap < maxSize)."],"exampleFix":"// before\nconst params = { maxSize: process.env.MAX_SIZE, overlap: 50 };\nawait chunk(docs, { strategy: 'character', params });\n// after\nconst params = { maxSize: Number(process.env.MAX_SIZE), overlap: 50 };\nawait chunk(docs, { strategy: 'character', params });","handlingStrategy":"validation","validationCode":"import { z } from 'zod';\nconst cfg = z.object({ maxSize: z.coerce.number().int().positive(), overlap: z.coerce.number().int().nonnegative() })\n  .refine(v => v.overlap < v.maxSize, { message: 'overlap must be < maxSize' });\nconst params = cfg.parse(rawParams);","typeGuard":"function isNumericParams(p: Record<string, unknown>): p is Record<string, number> {\n  return Object.values(p).every(v => typeof v === 'number' && Number.isFinite(v));\n}","tryCatchPattern":"try {\n  await chunk(docs, { strategy, params });\n} catch (e) {\n  if ((e as Error).message.includes('Invalid parameters')) {\n    console.error('Fix the parameters listed (path: message) before retrying');\n  }\n  throw e;\n}","preventionTips":["Coerce strings from env/config to numbers before passing params.","Pre-validate with the same Zod schemas the library uses for precise messages.","Ensure required strategy-specific fields are present with correct types.","Keep numeric constraints (positivity, overlap < maxSize) in your own config validation."],"tags":["rag","chunking","validation","zod","configuration"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}