RocketChat/Rocket.Chat · error · Meteor.Error

error-invalid-username

error-invalid-username

Error message

Invalid username

What it means

Thrown by _verifyRequiredFields when validating an outgoing integration whose `username` is missing, not a string, or blank after trimming. This username selects the 'post as' user for integration output (commonly rocket.cat) and later gets resolved against the Users collection, so a shape failure is rejected immediately with Meteor.Error code 'error-invalid-username'.

Source

Thrown at apps/meteor/server/lib/integrations/lib/validateOutgoingIntegration.ts:28

import { hasPermissionAsync, hasAllPermissionAsync } from '../../authorization/hasPermission';

const scopedChannels = ['all_public_channels', 'all_private_groups', 'all_direct_messages'];
const validChannelChars = ['@', '#'];

function _verifyRequiredFields(integration: INewOutgoingIntegration | IUpdateOutgoingIntegration): void {
	if (
		!integration.event ||
		!Match.test(integration.event, String) ||
		integration.event.trim() === '' ||
		!outgoingEvents[integration.event]
	) {
		throw new Meteor.Error('error-invalid-event-type', 'Invalid event type', {
			function: 'validateOutgoing._verifyRequiredFields',
		});
	}

	if (!integration.username || !Match.test(integration.username, String) || integration.username.trim() === '') {
		throw new Meteor.Error('error-invalid-username', 'Invalid username', {
			function: 'validateOutgoing._verifyRequiredFields',
		});
	}

	if (outgoingEvents[integration.event].use.targetRoom && !integration.targetRoom) {
		throw new Meteor.Error('error-invalid-targetRoom', 'Invalid Target Room', {
			function: 'validateOutgoing._verifyRequiredFields',
		});
	}

	if (!Match.test(integration.urls, [String])) {
		throw new Meteor.Error('error-invalid-urls', 'Invalid URLs', {
			function: 'validateOutgoing._verifyRequiredFields',
		});
	}

	integration.urls = integration.urls.filter((url) => url && url.trim() !== '');

View on GitHub (pinned to b2c16d5842)

Solutions

1. Include a non-empty string username, usually 'rocket.cat' or a dedicated bot account
2. Trim the input client-side and reject blank values before calling the API
3. Make sure you send the username (e.g. 'rocket.cat'), not the user _id

Example fix

// before
{ type: 'webhook-outgoing', event: 'sendMessage', username: '', urls: [...] }

// after
{ type: 'webhook-outgoing', event: 'sendMessage', username: 'rocket.cat', urls: [...] }

if (typeof integration.username !== 'string' || integration.username.trim() === '') {
  throw new TypeError('outgoing integrations need a non-empty username (post-as user)');
}

When it happens

Trigger: POST /api/v1/integrations.create with type 'webhook-outgoing' and no username field, username: '' or ' ', or username passed as a user _id / object instead of the username string.

Common situations: Forms that submit before the 'Post as' field is chosen; scripts that build the payload from optional environment variables that are unset; confusion between userId and username in the payload.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• history-data-must-be-defined
• error-invalid-event-type
• error-invalid-targetRoom
• error-invalid-urls
• error-invalid-channel-start-with-chars

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