{"record":{"id":"d9178d1a7a31d9b8","repo":"apify/crawlee","slug":"result-error-argumentvalidationerror-for-value","errorCode":null,"errorMessage":"${result.error} (ArgumentValidationError for value: ${value}, label: ${label})","messagePattern":"(.+?) \\(ArgumentValidationError for value: (.+?), label: (.+?)\\)","errorType":"validation","errorClass":"ArgumentValidationError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/internals/validation.ts","lineNumber":149,"sourceCode":"        this.cause = error;\n    }\n}\n\n/**\n * Parses `value` with `schema`, returning the typed result (with schema defaults applied).\n * Throws {@link ArgumentValidationError} on failure.\n *\n * The optional `label` names the interface being validated and is appended to every error line\n * (e.g. ``… at `maxRequestRetries` in `BasicCrawlerOptions` ``).\n * @internal\n */\nexport function parseArgument<TValue, TSchema extends z.ZodType>(\n    value: TValue,\n    schema: TSchema,\n    label?: string,\n): TValue & z.output<TSchema> {\n    const result = schema.safeParse(value);\n    if (!result.success) throw new ArgumentValidationError(result.error, value, label);\n    return result.data as TValue & z.output<TSchema>;\n}\n","sourceCodeStart":131,"sourceCodeEnd":152,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/utils/src/internals/validation.ts#L131-L152","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nnew BasicCrawler({ maxConcurrency: '10', minConcurrency: 20 });\n// throws: Invalid input (ArgumentValidationError for value: ..., label: maxConcurrency)\n\n// after\nnew BasicCrawler({ maxConcurrency: 10, minConcurrency: 1 });","handlingStrategy":"validation","validationCode":"import { z } from 'zod';\nconst optsSchema = z.object({\n  navigationTimeoutSecs: z.number().positive(),\n  maxConcurrency: z.number().int().positive(),\n  minConcurrency: z.number().int().nonnegative(),\n}).refine((o) => o.minConcurrency <= o.maxConcurrency, { message: 'minConcurrency must be <= maxConcurrency' });\nconst check = optsSchema.safeParse(myOptions);\nif (!check.success) console.error(check.error.issues);","typeGuard":"function isParsedOptions<T extends z.ZodType>(v: unknown, schema: T): v is z.output<T> {\n  return schema.safeParse(v).success;\n}","tryCatchPattern":"let crawler;\ntry {\n  crawler = new BasicCrawler(options);\n} catch (err) {\n  if ((err as Error).name === 'ArgumentValidationError') {\n    console.error('Invalid crawler options:', (err as any).cause?.issues ?? err);\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["validation","zod","configuration"],"backgroundTag":"schema-validation-failed","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}