{"record":{"id":"7b19810de791a3e0","repo":"FuelLabs/fuels-ts","slug":"number-too-big","errorCode":"NUMBER_TOO_BIG","errorMessage":"Value ${bnValue} is too large to be represented as a number, use string instead.","messagePattern":"Value (.+?) is too large to be represented as a number, use string instead\\.","errorType":"exception","errorClass":"FuelError","httpStatus":null,"severity":"error","filePath":"packages/math/src/bn.ts","lineNumber":61,"sourceCode":"\nexport class BN extends BnJs implements BNInputOverrides, BNHiddenTypes, BNHelper, BNOverrides {\n  MAX_U64 = '0xFFFFFFFFFFFFFFFF';\n\n  constructor(value?: BNInput | null, base?: number | 'hex', endian?: BnJs.Endianness) {\n    let bnValue = value;\n    let bnBase = base;\n\n    if (BN.isBN(value)) {\n      bnValue = value.toArray();\n    }\n    // trim '0x' from hex strings as BN doesn't support it - https://github.com/ChainSafe/web3.js/issues/3847\n    else if (typeof value === 'string' && value.slice(0, 2) === '0x') {\n      bnValue = value.substring(2);\n      bnBase = base || 'hex';\n    }\n\n    if (typeof bnValue === 'number' && bnValue > Number.MAX_SAFE_INTEGER) {\n      throw new FuelError(\n        ErrorCode.NUMBER_TOO_BIG,\n        `Value ${bnValue} is too large to be represented as a number, use string instead.`\n      );\n    }\n\n    super(bnValue == null ? 0 : bnValue, bnBase, endian);\n  }\n\n  // ANCHOR: HELPERS\n  // make sure we always include `0x` in hex strings\n  override toString(base?: number | 'hex', length?: number) {\n    const output = super.toString(base, length);\n\n    if (base === 16 || base === 'hex') {\n      return `0x${output}`;\n    }\n\n    return output;","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/FuelLabs/fuels-ts/blob/b3f37c91aca4aa9d5e4c0d3967f66237190826ea/packages/math/src/bn.ts#L43-L79","documentation":"Thrown by the BN constructor when the input is a JS number larger than Number.MAX_SAFE_INTEGER (2^53 - 1). Above that bound, JavaScript numbers lose integer precision, so the SDK refuses to construct a BN from them and asks you to pass the value as a string to preserve all digits.","triggerScenarios":"Constructing `new BN(number)` / `bn(number)` where number is a numeric literal or computed number exceeding 9007199254740991.","commonSituations":"Hard-coding a large token amount as a number literal, multiplying two numbers into a huge result then wrapping in BN, reading a Number from JSON instead of a string.","solutions":["Pass the value as a decimal or hex string: `bn('9007199254740992')` or `bn('0x...')`.","Keep large values as strings end-to-end (API responses, config) rather than coercing to Number.","If computing, do the arithmetic inside BN, not on JS numbers."],"exampleFix":"// before\nconst amount = bn(10000000000000000000); // > MAX_SAFE_INTEGER\n// after\nconst amount = bn('10000000000000000000');","handlingStrategy":"validation","validationCode":"const MAX_SAFE = Number.MAX_SAFE_INTEGER;\nfunction toBN(v: number | string): import('@fuel-ts/math').BN {\n  if (typeof v === 'number' && v > MAX_SAFE) {\n    throw new Error('pass large numbers as strings');\n  }\n  return bn(v);\n}","typeGuard":"const isSafeNumberInput = (v: unknown): boolean =>\n  typeof v !== 'number' || v <= Number.MAX_SAFE_INTEGER;","tryCatchPattern":null,"preventionTips":["Always pass large amounts as strings.","Type API surfaces as string for numeric fields, not number.","Avoid arithmetic on JS numbers before wrapping in BN."],"tags":["math","bn","precision","number","conversion"],"backgroundTag":null,"analyzedSha":"b3f37c91aca4aa9d5e4c0d3967f66237190826ea","analyzedAt":"2026-08-12T20:30:56.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}