{"record":{"id":"259f20bea729ca05","repo":"denoland/deno","slug":"cannot-convert-a-bigint-value-to-a-number","errorCode":null,"errorMessage":"Cannot convert a BigInt value to a number","messagePattern":"Cannot convert a BigInt value to a number","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"ext/webidl/00_webidl.js","lineNumber":119,"sourceCode":"// allocate a fresh `{ __proto__: null }` on every call. Converters only read\n// from `opts` -- never mutate -- so a shared frozen object is safe.\nconst EMPTY_OPTS = ObjectFreeze({ __proto__: null });\n\nfunction makeException(ErrorType, message, prefix, context, code = undefined) {\n  const err = new ErrorType(\n    `${prefix ? prefix + \": \" : \"\"}${context ? context : \"Value\"} ${message}`,\n  );\n  // Optional Node-compatible error code (e.g. ERR_INVALID_ARG_TYPE) so that\n  // node:* consumers observing `err.code` behave the same as on Node.\n  if (code !== undefined) {\n    err.code = code;\n  }\n  return err;\n}\n\nfunction toNumber(value) {\n  if (typeof value === \"bigint\") {\n    throw new TypeError(\"Cannot convert a BigInt value to a number\");\n  }\n  return Number(value);\n}\n\nfunction type(V) {\n  if (V === null) {\n    return \"Null\";\n  }\n  switch (typeof V) {\n    case \"undefined\":\n      return \"Undefined\";\n    case \"boolean\":\n      return \"Boolean\";\n    case \"number\":\n      return \"Number\";\n    case \"string\":\n      return \"String\";\n    case \"symbol\":","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/denoland/deno/blob/f7822238cab635a3a19f99f493f675fa81a7f9d8/ext/webidl/00_webidl.js#L101-L137","documentation":"This TypeError comes from Deno's WebIDL conversion layer (ext/webidl/00_webidl.js), used by every web API that takes a numeric argument. When a value must be converted to a WebIDL numeric type (long, double, etc.), the toNumber() helper explicitly rejects bigint so the implicit, lossy BigInt-to-Number conversion cannot happen silently. You hit it by passing a BigInt (e.g. 10n) to any web API number parameter.","triggerScenarios":"performance.now()-style timestamps stored as BigInt passed back into an API; API counters from BigInt arithmetic fed into numeric options; crypto or hash outputs (BigInt) passed to numeric parameters; calling web APIs from code that uses BigInt for large IDs.","commonSituations":"Mixed codebases mixing BigInt (for 64-bit IDs) with web API calls; converting Node Buffer/uint64 values to BigInt and forwarding them; refactors that changed a field from Number to BigInt and broke downstream API calls; JSON.parse producing Numbers while other layers produce BigInts.","solutions":["Convert explicitly before the call: Number(bigintValue) (safe if the value fits in a double).","For values beyond Number.MAX_SAFE_INTEGER, restructure the API usage — no web API accepts BigInt numerics.","Find where the BigInt originated (uint64 parsing, 10n literals) and keep numbers as Number unless precision demands BigInt.","Type your boundaries: annotate API-facing fields as number so TypeScript flags BigInt at compile time."],"exampleFix":"// before\nconst id = 9007199254740993n;\nperformance.measure(\"m\", { start: Number(id) , duration: BigInt(10) });\n\n// after\nconst id = 9007199254740993n;\nperformance.measure(\"m\", { start: Number(id), duration: 10 });","handlingStrategy":"type-guard","validationCode":"function toWebNumber(v) {\n  if (typeof v === \"bigint\") {\n    if (v > BigInt(Number.MAX_SAFE_INTEGER)) {\n      throw new RangeError(\"value loses precision as Number\");\n    }\n    return Number(v);\n  }\n  return v;\n}\nperformance.measure(\"m\", { start: toWebNumber(startTs) });","typeGuard":"function isNotBigInt(v) {\n  return typeof v !== \"bigint\";\n}","tryCatchPattern":"try { apiCall(value); } catch (e) { if (e instanceof TypeError && e.message.includes(\"BigInt\")) apiCall(Number(value)); else throw e; }","preventionTips":["Convert BigInt to Number explicitly at web API boundaries.","Keep timestamps and counters as Number unless >2^53 precision is required.","Use TypeScript numeric types on API-facing signatures so BigInt is rejected at compile time."],"tags":["webidl","bigint","type-conversion","typeerror","web-api"],"backgroundTag":"bigint-to-number-conversion","analyzedSha":"f7822238cab635a3a19f99f493f675fa81a7f9d8","analyzedAt":"2026-08-20T13:07:44.778Z","contentChangedAt":"2026-08-20T13:07:44.778Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}