{"record":{"id":"1c1ae60779aa5c72","repo":"FuelLabs/fuels-ts","slug":"encode-error-1c1ae6","errorCode":"ENCODE_ERROR","errorMessage":"Invalid ${this.type} type - number value is too large. Number can only safely handle up to 53 bits.","messagePattern":"Invalid (.+?) type - number value is too large\\. Number can only safely handle up to 53 bits\\.","errorType":"error_code","errorClass":"FuelError","httpStatus":null,"severity":"error","filePath":"packages/abi-coder/src/encoding/coders/BigNumberCoder.ts","lineNumber":27,"sourceCode":"\nconst encodedLengths: { [key in BigNumberCoderType]: number } = {\n  u64: WORD_SIZE,\n  u256: WORD_SIZE * 4,\n};\n\nexport class BigNumberCoder extends Coder<BNInput, BN> {\n  constructor(baseType: BigNumberCoderType) {\n    super('bigNumber', baseType, encodedLengths[baseType]);\n  }\n\n  encode(value: BNInput): Uint8Array {\n    let bytes;\n\n    // We throw an error if the value is a number and it's more than the max safe integer\n    // This is because we can experience some odd behavior with integers more than the max safe integer\n    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER#description\n    if (typeof value === 'number' && value > Number.MAX_SAFE_INTEGER) {\n      throw new FuelError(\n        ErrorCode.ENCODE_ERROR,\n        `Invalid ${this.type} type - number value is too large. Number can only safely handle up to 53 bits.`\n      );\n    }\n\n    try {\n      bytes = toBytes(value, this.encodedLength);\n    } catch (error) {\n      throw new FuelError(ErrorCode.ENCODE_ERROR, `Invalid ${this.type}.`);\n    }\n\n    return bytes;\n  }\n\n  decode(data: Uint8Array, offset: number): [BN, number] {\n    if (data.length < this.encodedLength) {\n      throw new FuelError(ErrorCode.DECODE_ERROR, `Invalid ${this.type} data size.`);\n    }","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/FuelLabs/fuels-ts/blob/b3f37c91aca4aa9d5e4c0d3967f66237190826ea/packages/abi-coder/src/encoding/coders/BigNumberCoder.ts#L9-L45","documentation":"Thrown by BigNumberCoder.encode (u64 or u256; this.type is the baseType) when typeof value === 'number' and value > Number.MAX_SAFE_INTEGER (2^53 - 1). The full message reads \"Invalid <u64|u256> type - number value is too large. Number can only safely handle up to 53 bits.\". The library refuses JS numbers beyond safe-integer range because they silently lose precision, which would corrupt on-chain amounts.","triggerScenarios":"Calling new BigNumberCoder('u64').encode(amount) — or encoding a u64/u256 Sway function argument — with a plain JS number greater than 9007199254740991. Common with token amounts, block numbers scaled up, or computed products of large numbers.","commonSituations":"Passing wei-like token amounts as Number instead of string/BN; arithmetic that overflows safe integer range; values read from JSON as numbers instead of strings; misunderstanding that u64/u256 can exceed 53 bits.","solutions":["Pass the value as a string (e.g. '9007199254740992') or a BN, not a number.","Keep large amounts as strings end-to-end (config, API responses, inputs).","If you must compute, use bn() and do arithmetic on BN objects.","Add a guard that converts any number > MAX_SAFE_INTEGER to a string before encode."],"exampleFix":"// before\nbigNumberCoder.encode(10 ** 18) // > MAX_SAFE_INTEGER → throws\n\n// after\nbigNumberCoder.encode('1000000000000000000') // string is safe","handlingStrategy":"validation","validationCode":"if (typeof value === 'number' && value > Number.MAX_SAFE_INTEGER) {\n  throw new Error('value too large for a JS number; pass a string or BN')\n}\nbigNumberCoder.encode(value)","typeGuard":"const isSafeNumberOrString = (v: unknown): boolean =>\n  typeof v !== 'number' || v <= Number.MAX_SAFE_INTEGER","tryCatchPattern":"try { bigNumberCoder.encode(value) }\ncatch (e) { if ((e as FuelError).code === ErrorCode.ENCODE_ERROR) { /* convert to string/BN and retry */ } throw e }","preventionTips":["Represent token amounts and large integers as strings everywhere.","Do arithmetic on BN objects, never on plain numbers near the limit.","Parse JSON big numbers with a reviver that keeps them as strings."],"tags":["abi-coder","encoding","u64","u256","number-precision","bignum"],"backgroundTag":null,"analyzedSha":"b3f37c91aca4aa9d5e4c0d3967f66237190826ea","analyzedAt":"2026-08-12T20:30:56.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}