discordjs/discord.js · error · Error

BitFieldInvalid: ${JSON.stringify(bit)}

Error message

BitFieldInvalid: ${JSON.stringify(bit)}

What it means

BitField.resolve() normalizes strings, numbers, and BigInts into a BigInt; if the input is a string that is not numeric and not a known flag name (or is another unsupported type), it throws Error('BitFieldInvalid: <json>').

Source

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

	 *
	 * @param bit - bit(s) to resolve
	 * @returns the numeric value of the bit fields
	 */
	public static resolve<Flags extends string = string>(bit: BitFieldResolvable<Flags>): bigint {
		const DefaultBit = this.DefaultBit;
		if (typeof bit === 'bigint' && bit >= DefaultBit) return bit;
		if (typeof bit === 'number' && BigInt(bit) >= DefaultBit) return BigInt(bit);
		if (bit instanceof BitField) return bit.bitField;
		if (Array.isArray(bit)) {
			return bit.map((bit_) => this.resolve(bit_)).reduce((prev, bit_) => prev | bit_, DefaultBit);
		}

		if (typeof bit === 'string') {
			if (!Number.isNaN(Number(bit))) return BigInt(bit);
			if (bit in this.Flags) return this.Flags[bit as keyof typeof this.Flags];
		}

		throw new Error(`BitFieldInvalid: ${JSON.stringify(bit)}`);
	}
}

View on GitHub (pinned to a81ed8a306)

Solutions

  1. Use a valid flag key exactly as defined in BitField.Flags (verify with Object.keys(Flags))
  2. Pass a numeric or BigInt value instead of a string if you have the raw bits
  3. Validate the string with `bit in Flags` (or Number.isNaN check for numeric strings) before resolving

Example fix

// before
const perms = new Permissions('administrator');
// after
const perms = new Permissions('Administrator'); // exact flag name
// or guard:
if (!(name in Permissions.Flags)) throw new Error(`Unknown flag: ${name}`);
Defensive patterns

Strategy: validation

Validate before calling

const FLAGS = Permissions.Flags;
function isKnownFlag(s: string): boolean {
  return /^\d+$/.test(s) || s in FLAGS;
}

Type guard

function isResolvableBit(b: unknown, flags: Record<string, number | bigint>): b is string | number | bigint {
  if (typeof b === 'number' || typeof b === 'bigint') return true;
  if (typeof b === 'string') return !Number.isNaN(Number(b)) || b in flags;
  return false;
}

Try / catch

try {
  const perms = new Permissions(userInput);
} catch (err) {
  if (err.message.startsWith('BitFieldInvalid:')) {
    console.error(`Unknown flag/bits: ${userInput}`);
  }
}

Prevention

When it happens

Trigger: new Permissions('SendMesage') (typo in flag name), passing an arbitrary string like 'read messages', or passing an object/array to a BitField constructor/any()/add()/remove().

Common situations: Flag-name typos, camelCase vs PascalCase confusion ('sendMessages' vs 'SendMessages'), user-supplied strings from config or CLI, or version changes renaming flags.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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