discordjs/discord.js · error · Error

Phone number must start with a "+" sign.

Error message

Phone number must start with a "+" sign.

What it means

`@sapphire/format-util`'s `phoneNumber()` wraps a phone number in angle brackets for mention-style formatting and requires it to start with a `+` (E.164 country-code prefix). Although TypeScript's `+${string}` template type enforces this at compile time, at runtime the function defensively throws a plain Error when the input lacks the leading `+`.

Source

Thrown at packages/formatters/src/formatters.ts:707

		const searchParams = new URLSearchParams(
			Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value])),
		);

		return `<${email}?${searchParams.toString()}>` as const;
	}

	return `<${email}>` as const;
}

/**
 * Formats a phone number into a phone number mention.
 *
 * @typeParam PhoneNumber - This is inferred by the supplied phone number
 * @param phoneNumber - The phone number to format. Must start with a `+` sign.
 */
export function phoneNumber<PhoneNumber extends `+${string}`>(phoneNumber: PhoneNumber) {
	if (!phoneNumber.startsWith('+')) {
		throw new Error('Phone number must start with a "+" sign.');
	}

	return `<${phoneNumber}>` as const;
}

/**
 * The {@link https://discord.com/developers/docs/reference#message-formatting-timestamp-styles | message formatting timestamp styles}
 * supported by Discord.
 */
export const TimestampStyles = {
	/**
	 * Short time format, consisting of hours and minutes.
	 *
	 * @example `16:20`
	 */
	ShortTime: 't',

	/**

View on GitHub (pinned to a81ed8a306)

Solutions

1. Prepend '+' to the number before calling, after normalizing away spaces/dashes/parentheses.
2. Store and transmit numbers in E.164 format (e.g. +15551234567).
3. Add a runtime validation/normalization step since JS callers get no compile-time protection.
4. If the country is known, prepend its dial code (e.g. '+1' for US).

Example fix

// before
phoneNumber(rawPhone); // '555-123-4567'
// after
const normalized = '+' + rawPhone.replace(/\D/g, '');
phoneNumber(normalized); // '+5551234567'

const toE164 = (raw, defaultCountry = '1') => {
  const digits = String(raw).replace(/\D/g, '');
  if (!digits) throw new Error('Empty phone number');
  return '+' + digits;
};

const isE164 = (s) => typeof s === 'string' && /^\+\d{7,15}$/.test(s);

try {
  const formatted = phoneNumber(rawPhone);
} catch (err) {
  if (err.message.includes('must start with a "+"')) {
    console.error('Phone numbers must be in E.164 format, e.g. +15551234567');
  } else throw err;
}

When it happens

Trigger: Calling `phoneNumber('15551234567')` with a number missing the leading `+`; passing a value read from user input or a database that stored digits only; JS callers (no type checking) passing any string.

Common situations: Phone numbers stored without country code in a database; forms stripping the '+' character; users typing numbers without the international prefix; JavaScript projects bypassing TypeScript typing.

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