{"record":{"id":"c9d78df66eaf63a3","repo":"denoland/deno","slug":"batchsize-must-be-a-positive-integer-received-b","errorCode":null,"errorMessage":"batchSize must be a positive integer: received ${batchSize}","messagePattern":"batchSize must be a positive integer: received (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"ext/kv/01_db.ts","lineNumber":250,"sourceCode":"      limit?: number;\n      batchSize?: number;\n      cursor?: string;\n      reverse?: boolean;\n      consistency?: Deno.KvConsistencyLevel;\n    } = { __proto__: null },\n  ): KvListIterator {\n    if (\n      options.limit !== undefined &&\n      (!NumberIsInteger(options.limit) || options.limit <= 0)\n    ) {\n      throw new Error(\n        `Limit must be a positive integer: received ${options.limit}`,\n      );\n    }\n\n    let batchSize = options.batchSize ?? (options.limit ?? 100);\n    if (!NumberIsInteger(batchSize) || batchSize <= 0) {\n      throw new Error(\n        `batchSize must be a positive integer: received ${batchSize}`,\n      );\n    }\n    if (options.batchSize === undefined && batchSize > 500) batchSize = 500;\n\n    return new KvListIterator({\n      limit: options.limit,\n      selector,\n      cursor: options.cursor,\n      reverse: options.reverse ?? false,\n      consistency: options.consistency ?? \"strong\",\n      batchSize,\n      pullBatch: this.#pullBatch(batchSize),\n    });\n  }\n\n  #pullBatch(batchSize: number): (\n    selector: Deno.KvListSelector,","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/denoland/deno/blob/9ad36f7a2cce60488e6ec52283efb32efddaf93a/ext/kv/01_db.ts#L232-L268","documentation":"Kv.list()'s batchSize (entries fetched per internal snapshot read) must be a positive integer. It defaults to `limit ?? 100` and is silently capped to 500 only when derived from limit; an explicitly provided batchSize that is 0, negative, fractional, NaN, or a non-number throws 'batchSize must be a positive integer: received <value>'. Because limit is validated first and the derived fallback comes from it, this error in practice means the batchSize you passed explicitly is invalid.","triggerScenarios":"`kv.list(sel, { batchSize: 0 })`, `{ batchSize: 10.5 }`, `{ batchSize: \"50\" }` (string), or options objects built by spreading config where batchSize is an invalid value rather than undefined (undefined falls back to limit or 100 and never throws here).","commonSituations":"Throughput tuning with a config-provided batchSize that arrives as a string or 0; copying limit semantics onto batchSize; schemas or defaults objects that permit 0 as a 'no preference' value.","solutions":["Pass a positive integer between 1 and 500 (explicit larger values are accepted but each batch snapshot reads that many entries — prefer <= 500).","Validate like limit: Number.isInteger(batchSize) && batchSize > 0.","Omit batchSize to inherit limit (capped at 500) or the default of 100.","Coerce once at the config boundary: batchSize: Number(cfg.batchSize) with a fallback."],"exampleFix":"// before\nconst it = kv.list(sel, { batchSize: cfg.batchSize }); // cfg.batchSize = \"50\" or 0\n\n// after\nconst batchSize = Number.isInteger(Number(cfg.batchSize)) && Number(cfg.batchSize) > 0\n  ? Number(cfg.batchSize)\n  : undefined; // undefined -> safe default\nconst it = kv.list(sel, batchSize ? { batchSize } : {});","handlingStrategy":"validation","validationCode":"const batchSize =\n  cfg.batchSize === undefined || cfg.batchSize === null\n    ? undefined // safe default (limit ?? 100, capped 500)\n    : Number(cfg.batchSize);\nif (batchSize !== undefined && (!Number.isInteger(batchSize) || batchSize <= 0)) {\n  throw new Error(`bad batchSize from config: ${cfg.batchSize}`);\n}\nconst it = kv.list(selector, batchSize ? { batchSize } : {});","typeGuard":"const isPositiveInt = (v: unknown): v is number =>\n  typeof v === \"number\" && Number.isInteger(v) && v > 0;","tryCatchPattern":null,"preventionTips":["Parse batchSize config once with Number() and a sane default","Keep explicit batchSize in 1..500","Treat 0 in config as 'use default' (map to undefined), never pass it through"],"tags":["deno-kv","kv-list","batch-size","pagination","argument-validation"],"backgroundTag":"invalid-batch-size","analyzedSha":"9ad36f7a2cce60488e6ec52283efb32efddaf93a","analyzedAt":"2026-08-20T13:07:44.778Z","contentChangedAt":"2026-08-20T13:07:44.778Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}