discordjs/discord.js · error · RangeError

Cannot convert bitfield value ${this.bitField} to number, as

Error message

Cannot convert bitfield value ${this.bitField} to number, as it is bigger than ${Number.MAX_SAFE_INTEGER} (the maximum safe integer)

What it means

BitField.toJSON(asNumber) converts the bitfield to a number when asNumber is true, but BigInt values exceed Number.MAX_SAFE_INTEGER cannot be represented exactly, so a RangeError is thrown to prevent silent precision loss.

Source

Thrown at packages/structures/src/bitfields/BitField.ts:160

		}

		return serialized;
	}

	/**
	 * Gets an Array of bit field names based on the bits available.
	 *
	 * @param hasParams - Additional parameters for the has method, if any
	 * @returns An Array of bit field names
	 */
	public toArray(...hasParams: readonly unknown[]) {
		return [...this[Symbol.iterator](...hasParams)];
	}

	public toJSON(asNumber?: boolean) {
		if (asNumber) {
			if (this.bitField > Number.MAX_SAFE_INTEGER) {
				throw new RangeError(
					`Cannot convert bitfield value ${this.bitField} to number, as it is bigger than ${Number.MAX_SAFE_INTEGER} (the maximum safe integer)`,
				);
			}

			return Number(this.bitField);
		}

		return this.bitField.toString();
	}

	public valueOf() {
		return this.bitField;
	}

	public *[Symbol.iterator](...hasParams: unknown[]) {
		for (const bitName of Object.keys(this.constructor.Flags)) {
			if (Number.isNaN(Number(bitName)) && this.has(bitName as Flags, ...hasParams)) yield bitName as Flags;
		}

View on GitHub (pinned to a81ed8a306)

Solutions

1. Call toJSON() without arguments to get the string/array form instead of a number
2. Use toString()/BigInt output when the value may exceed MAX_SAFE_INTEGER
3. Reduce the flags combined if you truly need a safe numeric representation

Example fix

// before
const num = permissions.toJSON(true);
// after
const str = permissions.toJSON(); // string form, safe for big values
const num = BigInt(str) <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(str) : str;

if (typeof bf.bitField === 'bigint' && bf.bitField > BigInt(Number.MAX_SAFE_INTEGER)) {
  // use string serialization instead of toJSON(true)
}

function isSafeAsNumber(bf: BitField): boolean {
  return typeof bf.bitField === 'number' || bf.bitField <= BigInt(Number.MAX_SAFE_INTEGER);
}

try {
  const n = bitfield.toJSON(true);
} catch (err) {
  if (err instanceof RangeError && err.message.includes('MAX_SAFE_INTEGER')) {
    const s = bitfield.toJSON(); // string fallback
  }
}

When it happens

Trigger: Calling bitField.toJSON(true) (or JSON.stringify with a numeric replacer path) on a bitfield whose value is a BigInt larger than 2^53-1, e.g. large permission or intent combinations.

Common situations: Serializing Intents or Permissions bitfields that combine many flags, then requesting numeric output; logging with asNumber for compact output on wide bitfields.

Related errors

• Cannot properly serialize component type: ${data.type}
• BitFieldInvalid: ${JSON.stringify(bit)}

AI-assisted analysis of discordjs/discord.js@a81ed8a306 (2026-08-30). Data as JSON: /api/errors/a3206641a77eb163. Report an issue: GitHub.