apify/crawlee · error · ArgumentValidationError

${result.error} (ArgumentValidationError for value: ${value}

Error message

${result.error} (ArgumentValidationError for value: ${value}, label: ${label})

What it means

parseArgument runs a zod schema against a value and throws ArgumentValidationError carrying result.error (the ZodError), the offending value, and a label identifying which argument failed. It is used across Crawlee constructors (BasicCrawler options, browser pool, autoscaled pool, etc.) to validate option objects. The message embeds the zod issue text plus the label so you know exactly which option and which rule failed.

Source

Thrown at packages/utils/src/internals/validation.ts:149

        this.cause = error;
    }
}

/**
 * Parses `value` with `schema`, returning the typed result (with schema defaults applied).
 * Throws {@link ArgumentValidationError} on failure.
 *
 * The optional `label` names the interface being validated and is appended to every error line
 * (e.g. ``… at `maxRequestRetries` in `BasicCrawlerOptions` ``).
 * @internal
 */
export function parseArgument<TValue, TSchema extends z.ZodType>(
    value: TValue,
    schema: TSchema,
    label?: string,
): TValue & z.output<TSchema> {
    const result = schema.safeParse(value);
    if (!result.success) throw new ArgumentValidationError(result.error, value, label);
    return result.data as TValue & z.output<TSchema>;
}

View on GitHub (pinned to dbe57fb09c)

Solutions

Read the zod issue in the message/`error.cause` (or `result.error`): it names the path and expected type
Fix the flagged option's type/range (e.g. Number(option) for env-sourced strings)
Validate your options object with the same zod schema (or a quick safeParse) before constructing the crawler
Ensure numeric constraints hold (min<=max concurrency, ratios within 0-1, positive timeouts)
Check option names against the docs for the installed Crawlee version

Example fix

// before
new BasicCrawler({ maxConcurrency: '10', minConcurrency: 20 });
// throws: Invalid input (ArgumentValidationError for value: ..., label: maxConcurrency)

// after
new BasicCrawler({ maxConcurrency: 10, minConcurrency: 1 });

Defensive patterns

Strategy: validation

Validate before calling

import { z } from 'zod';
const optsSchema = z.object({
  navigationTimeoutSecs: z.number().positive(),
  maxConcurrency: z.number().int().positive(),
  minConcurrency: z.number().int().nonnegative(),
}).refine((o) => o.minConcurrency <= o.maxConcurrency, { message: 'minConcurrency must be <= maxConcurrency' });
const check = optsSchema.safeParse(myOptions);
if (!check.success) console.error(check.error.issues);

Type guard

function isParsedOptions<T extends z.ZodType>(v: unknown, schema: T): v is z.output<T> {
  return schema.safeParse(v).success;
}

Try / catch

let crawler;
try {
  crawler = new BasicCrawler(options);
} catch (err) {
  if ((err as Error).name === 'ArgumentValidationError') {
    console.error('Invalid crawler options:', (err as any).cause?.issues ?? err);
    process.exit(1);
  }
  throw err;
}

Prevention

Coerce env/config-sourced numbers with Number() before constructing crawlers
Keep concurrency invariants (min <= max, ratios within 0-1) in config validation
Pre-parse options with the same zod schemas in a startup step
Enable strict schema checks so typo'd option names surface early

When it happens

Trigger: Any constructor/options object failing its zod schema — e.g. negative or wrong-typed navigationTimeoutSecs, maxConcurrency < minConcurrency, string where number expected, invalid enum value for an option, missing required nested field in launchContext/fingerprintOptions.

Common situations: Reading crawler options from env/JSON/config where numbers arrive as strings; setting minConcurrency > maxConcurrency; ratio values outside 0..1; passing null where a nested object schema expects fields; typos in option names that zod strict-mode flags.

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 apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/d9178d1a7a31d9b8. Report an issue: GitHub.