FuelLabs/fuels-ts · error · FuelError

NUMBER_TOO_BIG

NUMBER_TOO_BIG

Error message

Value ${bnValue} is too large to be represented as a number, use string instead.

What it means

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.

Source

Thrown at packages/math/src/bn.ts:61

export class BN extends BnJs implements BNInputOverrides, BNHiddenTypes, BNHelper, BNOverrides {
  MAX_U64 = '0xFFFFFFFFFFFFFFFF';

  constructor(value?: BNInput | null, base?: number | 'hex', endian?: BnJs.Endianness) {
    let bnValue = value;
    let bnBase = base;

    if (BN.isBN(value)) {
      bnValue = value.toArray();
    }
    // trim '0x' from hex strings as BN doesn't support it - https://github.com/ChainSafe/web3.js/issues/3847
    else if (typeof value === 'string' && value.slice(0, 2) === '0x') {
      bnValue = value.substring(2);
      bnBase = base || 'hex';
    }

    if (typeof bnValue === 'number' && bnValue > Number.MAX_SAFE_INTEGER) {
      throw new FuelError(
        ErrorCode.NUMBER_TOO_BIG,
        `Value ${bnValue} is too large to be represented as a number, use string instead.`
      );
    }

    super(bnValue == null ? 0 : bnValue, bnBase, endian);
  }

  // ANCHOR: HELPERS
  // make sure we always include `0x` in hex strings
  override toString(base?: number | 'hex', length?: number) {
    const output = super.toString(base, length);

    if (base === 16 || base === 'hex') {
      return `0x${output}`;
    }

    return output;

View on GitHub (pinned to b3f37c91ac)

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.

Example fix

// before
const amount = bn(10000000000000000000); // > MAX_SAFE_INTEGER
// after
const amount = bn('10000000000000000000');

Defensive patterns

Strategy: validation

Validate before calling

const MAX_SAFE = Number.MAX_SAFE_INTEGER;
function toBN(v: number | string): import('@fuel-ts/math').BN {
  if (typeof v === 'number' && v > MAX_SAFE) {
    throw new Error('pass large numbers as strings');
  }
  return bn(v);
}

Type guard

const isSafeNumberInput = (v: unknown): boolean =>
  typeof v !== 'number' || v <= Number.MAX_SAFE_INTEGER;

Prevention

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.

When it happens

Trigger: Constructing `new BN(number)` / `bn(number)` where number is a numeric literal or computed number exceeding 9007199254740991.

Common situations: 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.

Related errors

AI-assisted analysis of FuelLabs/fuels-ts@b3f37c91ac (2026-08-12). Data as JSON: /api/errors/7b19810de791a3e0. Report an issue: GitHub.