{"record":{"id":"ea34859ec06d182f","repo":"agalwood/Motrix","slug":"callername-reserved-gid-must-contain-exactly-16","errorCode":null,"errorMessage":"${callerName} reserved gid must contain exactly 16 hexadecimal characters","messagePattern":"(.+?) reserved gid must contain exactly 16 hexadecimal characters","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/core/lib/ids.ts","lineNumber":21,"sourceCode":"\nexport function newTaskId(): string {\n  return uuidv7()\n}\n\n/**\n * Mint a caller-reserved aria2 gid: exactly 16 hex characters (lowercase\n * when self-minted). Prefers the injected override (deterministic tests /\n * shells) and validates whatever it returns — a malformed reserved gid\n * would silently break the reservation-shield protocol in TaskManager.\n * `callerName` keeps each dispatch site's original error message.\n */\nexport function newEngineTaskId(\n  override: (() => string) | undefined,\n  callerName: string\n): string {\n  const gid = override?.() ?? randomBytes(8).toString('hex')\n  if (!/^[0-9a-fA-F]{16}$/.test(gid)) {\n    throw new TypeError(\n      `${callerName} reserved gid must contain exactly 16 hexadecimal characters`\n    )\n  }\n  return gid\n}\n","sourceCodeStart":3,"sourceCodeEnd":27,"githubUrl":"https://github.com/agalwood/Motrix/blob/1a708ee57746c434e2c67a44bbf0906a976afea4/src/core/lib/ids.ts#L3-L27","documentation":"`newEngineTaskId` mints an aria2 group-id (gid): exactly 16 hexadecimal characters. It prefers the injected `override` (used for deterministic tests/shells) and validates whatever that override returns, because a malformed gid would silently break the reservation-shield protocol in `TaskManager`. The `callerName` prefix in the message identifies which dispatch site produced the bad gid. This is a `TypeError`, not a `RangeError` — it indicates a programmer/test-config error, not bad input data.","triggerScenarios":"Providing an `override` whose return value is not 16 hex chars — e.g. a UUID (36 chars), an off-by-one fixture returning a 15-char gid, or a hand-built gid with a non-hex character. The random fallback (`randomBytes(8).toString('hex')`) always produces 16 lowercase hex, so production without an override never hits this.","commonSituations":"Test overrides that return a hardcoded gid of the wrong length; configuration injection supplying a UUID instead of an aria2 gid; copy-pasting a gid from a different engine.","solutions":["Make the test override return `randomBytes(8).toString('hex')` or a literal 16-hex string like `'0123456789abcdef'`.","Audit the override for off-by-one length or non-hex characters (uppercase hex is allowed by the regex).","If you need a deterministic gid, derive it from a hex hash truncated/padded to 16 chars.","Remove the override in production code paths — overrides are for tests only."],"exampleFix":"// before\nnewEngineTaskId(() => 'abc123', 'TaskManager')  // 6 chars\n// after\nnewEngineTaskId(() => '000000000000abc1', 'TaskManager')  // 16 hex chars","handlingStrategy":"type-guard","validationCode":"function validateGid(gid: string): string {\n  if (!/^[0-9a-fA-F]{16}$/.test(gid))\n    throw new TypeError(`gid must be 16 hex chars, got: ${gid}`)\n  return gid\n}","typeGuard":"function isAria2Gid(v: unknown): v is string {\n  return typeof v === 'string' && /^[0-9a-fA-F]{16}$/.test(v)\n}","tryCatchPattern":"try {\n  newEngineTaskId(override, callerName)\n} catch (err) {\n  if (err instanceof TypeError && err.message.endsWith('reserved gid must contain exactly 16 hexadecimal characters')) {\n    newEngineTaskId(undefined, callerName)  // fall back to random\n  } else throw err\n}","preventionTips":["Only inject overrides in test code.","Verify the override returns 16 hex chars before wiring it in.","Uppercase hex is accepted; lengths other than 16 are not."],"tags":["validation","type-error","aria2","gid","tests"],"backgroundTag":null,"analyzedSha":"1a708ee57746c434e2c67a44bbf0906a976afea4","analyzedAt":"2026-08-12T16:18:09.346Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}