{"record":{"id":"8c6a9b4b417f04ec","repo":"jackwener/OpenCLI","slug":"name-must-be-a-non-negative-integer-got-raw","errorCode":null,"errorMessage":"${name} must be a non-negative integer (got \"${raw}\")","messagePattern":"(.+?) must be a non-negative integer \\(got \"(.+?)\"\\)","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/slock/resolve.js","lineNumber":62,"sourceCode":"  }\n  return v;\n}\n\nexport function parsePositiveInteger(value, name, { defaultValue, max } = {}) {\n  const raw = value === undefined || value === null || value === '' ? defaultValue : value;\n  const n = parseStrictInteger(raw);\n  if (!Number.isInteger(n) || n <= 0 || (max !== undefined && n > max)) {\n    const suffix = max !== undefined ? ` between 1 and ${max}` : ' as a positive integer';\n    throw new ArgumentError(`${name} must be${suffix} (got \"${raw}\")`);\n  }\n  return n;\n}\n\nexport function parseNonNegativeInteger(value, name, { defaultValue } = {}) {\n  const raw = value === undefined || value === null || value === '' ? defaultValue : value;\n  const n = parseStrictInteger(raw);\n  if (!Number.isInteger(n) || n < 0) {\n    throw new ArgumentError(`${name} must be a non-negative integer (got \"${raw}\")`);\n  }\n  return n;\n}\n\nfunction parseStrictInteger(raw) {\n  if (typeof raw === 'number')\n    return raw;\n  const text = String(raw);\n  if (!/^\\d+$/.test(text))\n    return NaN;\n  return Number(text);\n}\n","sourceCodeStart":44,"sourceCodeEnd":75,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/slock/resolve.js#L44-L75","documentation":"parseNonNegativeInteger throws ArgumentError when the value (after applying defaultValue for undefined/null/'') does not parse as a whole number >= 0. It is used for offset-style options where 0 is valid but negatives are not.","triggerScenarios":"Calling a command with an offset option set to a negative number (e.g. --offset -10), a float, or non-numeric text such as 'first' or 'undefined'.","commonSituations":"Hand-computed pagination offsets going negative on page 0 (`(page-1)*size` with page=0); scripts interpolating unset shell variables into the flag; copying `--offset=-1` from a buggy loop.","solutions":["Pass a whole number >= 0, e.g. --offset 0 for the first page.","Fix the pagination arithmetic producing a negative offset (clamp with Math.max(0, n)).","Omit the option to use the defaultValue."],"exampleFix":"// before\nconst offset = (page - 1) * size; // page=0 -> -25\n// after\nconst offset = Math.max(0, (page - 1) * size);","handlingStrategy":"validation","validationCode":"const offset = Math.max(0, Number.isInteger(Number(rawOffset)) ? Number(rawOffset) : 0);\nif (!Number.isInteger(offset) || offset < 0) throw new Error('offset must be >= 0');","typeGuard":"const isNonNegativeInt = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0;","tryCatchPattern":"try {\n  runCommand(['--offset', String(offset)]);\n} catch (e) {\n  if (e instanceof ArgumentError && /non-negative integer/.test(e.message)) {\n    console.error(`Offset \"${offset}\" invalid; using 0.`);\n    runCommand(['--offset', '0']);\n  } else throw e;\n}","preventionTips":["Clamp computed pagination offsets with Math.max(0, ...).","Initialize page counters to 1, not 0, when using (page-1)*size arithmetic.","Validate shell variables are set (${VAR:?msg}) before interpolating into CLI flags."],"tags":["cli","argument-validation","pagination"],"backgroundTag":"invalid-argument-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}