Invalid parameters for ${strategy} strategy: ${errorMessage}

Error message

Invalid parameters for ${strategy} strategy: ${errorMessage}

What it means

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.

Source

Thrown at packages/rag/src/document/validation.ts:142

  }

  const result = schema.safeParse(params);
  if (!result.success) {
    // Extract unrecognized keys for cleaner error message
    // Use 'issues' for Zod v4 compatibility (also available in Zod v3)
    const issues = result.error.issues;
    const unrecognizedError = issues.find((e: any) => e.code === 'unrecognized_keys');
    if (unrecognizedError && 'keys' in unrecognizedError) {
      const keys = (unrecognizedError as any).keys.join(', ');
      throw new Error(`Invalid parameters for ${strategy} strategy: '${keys}' not supported`);
    }

    // Fallback to general error message for other validation issues
    const errorMessage = issues
      .map((e: any) => `${e.path.length > 0 ? e.path.join('.') : 'parameter'}: ${e.message}`)
      .join(', ');

    throw new Error(`Invalid parameters for ${strategy} strategy: ${errorMessage}`);
  }
}

View on GitHub (pinned to 75dd419e61)

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).

Example fix

// before
const params = { maxSize: process.env.MAX_SIZE, overlap: 50 };
await chunk(docs, { strategy: 'character', params });
// after
const params = { maxSize: Number(process.env.MAX_SIZE), overlap: 50 };
await chunk(docs, { strategy: 'character', params });

Defensive patterns

Strategy: validation

Validate before calling

import { z } from 'zod';
const cfg = z.object({ maxSize: z.coerce.number().int().positive(), overlap: z.coerce.number().int().nonnegative() })
  .refine(v => v.overlap < v.maxSize, { message: 'overlap must be < maxSize' });
const params = cfg.parse(rawParams);

Type guard

function isNumericParams(p: Record<string, unknown>): p is Record<string, number> {
  return Object.values(p).every(v => typeof v === 'number' && Number.isFinite(v));
}

Try / catch

try {
  await chunk(docs, { strategy, params });
} catch (e) {
  if ((e as Error).message.includes('Invalid parameters')) {
    console.error('Fix the parameters listed (path: message) before retrying');
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/267bd4c32c9e370e. Report an issue: GitHub.