RocketChat/Rocket.Chat · error · Meteor.Error

error-invalid-username

error-invalid-username

Error message

Invalid username

What it means

checkUsernameAvailabilityWithValidation throws error-invalid-username (method 'setUsername') when the username argument is falsy: empty string, undefined, or null. This is the input-shape guard before any database lookup happens.

Source

Thrown at apps/meteor/server/lib/users/checkUsernameAvailability.ts:25

import { settings } from '../../settings';
import type { UsernameAvailabilityCheckType } from '../callbacks/checkUsernameAvailabilityCallback';
import { checkUsernameAvailabilityCallback } from '../callbacks/checkUsernameAvailabilityCallback';
import { validateName } from '../shared/validateName';

let usernameBlackList: RegExp[] = [];

const toRegExp = (username: string): RegExp => new RegExp(`^${escapeRegExp(username).trim()}$`, 'i');

settings.watch('Accounts_BlockedUsernameList', (value: string) => {
	usernameBlackList = ['all', 'here'].concat(value.split(',')).map(toRegExp);
});

const usernameIsBlocked = (username: string, usernameBlackList: RegExp[]): boolean | number =>
	usernameBlackList.length && usernameBlackList.some((restrictedUsername) => restrictedUsername.test(escapeRegExp(username).trim()));

export const checkUsernameAvailabilityWithValidation = async function (userId: string, username: string): Promise<boolean> {
	if (!username) {
		throw new Meteor.Error('error-invalid-username', 'Invalid username', { method: 'setUsername' });
	}

	const user = await Users.findOneById(userId, { projection: { username: 1 } });

	if (!user) {
		throw new Meteor.Error('error-invalid-user', 'Invalid user', { method: 'setUsername' });
	}

	if (user.username && !settings.get('Accounts_AllowUsernameChange')) {
		throw new Meteor.Error('error-not-allowed', 'Not allowed', { method: 'setUsername' });
	}

	if (user.username === username) {
		return true;
	}
	return checkUsernameAvailability(username);
};

View on GitHub (pinned to b2c16d5842)

Solutions

1. Guard the form: require a non-empty trimmed username before invoking the method
2. Check for undefined/null earlier in the call chain (the guard only catches falsy values, not whitespace-only strings)
3. Disable the submit action while the field is empty

Example fix

// before
Meteor.call('setUsername', usernameInput.value); // '' -> error-invalid-username

// after
const username = usernameInput.value?.trim();
if (!username) {
  showFieldError('Username is required');
} else {
  Meteor.call('setUsername', username);
}

const username = raw?.trim();
if (!username) {
  throw new Error('Username is required');
}
await checkUsernameAvailabilityWithValidation(userId, username);

const isNonEmptyUsername = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;

When it happens

Trigger: Calling setUsername (or a flow that wraps this validation) with an empty form field, a variable that was never assigned, or a value that serializes to '' such as username.trim() of whitespace-only input.

Common situations: Profile form submitted with the username field cleared; onboarding step skipped; client sending undefined because the input state key is misspelled.

Related errors

• error-blocked-username
• error-input-is-not-a-valid-field
• error-user-not-found
• error-user-param-not-provided
• error-invalid-user

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/fae109006338870d. Report an issue: GitHub.