What causes "auth option should be of the form "username:password"" in RocketChat/Rocket.Chat?

In the integration's Prepare Outgoing Requests script, return auth as a single 'username:password' string, e.g. `return { url, method: 'POST', auth: `${user}:${password}` };`

RocketChat/Rocket.Chat · error · Error

auth option should be of the form "username:password"

Error message

auth option should be of the form "username:password"

What it means

Thrown by the outgoing-webhook trigger handler in executeTriggerUrl after an integration's 'Prepare Outgoing Requests' script returns an opts object whose `auth` string contains no ':' character. Mirroring Meteor's HTTP.call behavior, the server converts opts.auth into a Basic Authorization header (`Basic base64(user:pass)`), which is only possible when the value separates username and password with a colon. The error aborts the webhook execution before any HTTP request is made.

Source

Thrown at apps/meteor/server/lib/integrations/lib/triggerHandler.ts:596

				await updateHistory({ historyId, step: 'after-prepare-send-message-failed', finished: true });
				return;
			}
			await updateHistory({
				historyId,
				step: 'after-prepare-send-message',
				prepareSentMessage: prepareMessage,
			});
		}

		if (!opts.url || !opts.method) {
			await updateHistory({ historyId, step: 'after-prepare-no-url_or_method', finished: true });
			return;
		}

		// based on HTTP.call implementation
		if (opts.auth) {
			if (opts.auth.indexOf(':') < 0) {
				throw new Error('auth option should be of the form "username:password"');
			}

			const base64 = Buffer.from(opts.auth, 'ascii').toString('base64');
			opts.headers.Authorization = `Basic ${base64}`;
		}

		await updateHistory({
			historyId,
			step: 'pre-http-call',
			url: opts.url,
			httpCallData: opts.data,
		});

		if (opts.data) {
			opts.headers['Content-Type'] = 'application/json';
		}

		fetch(

View on GitHub (pinned to b2c16d5842)

Solutions

In the integration's Prepare Outgoing Requests script, return auth as a single 'username:password' string, e.g. `return { url, method: 'POST', auth: `${user}:${password}` };`
For token/Bearer schemes do not use `auth` at all; set the header directly: `headers: { Authorization: `Bearer ${token}` }`
If user or password contain reserved characters, wrap each part with encodeURIComponent while keeping exactly one ':' separator
Open Admin -> Integrations -> (integration) -> History and inspect the last steps (after-maybe-ran-prepare) to see exactly what the script returned before fixing it

Example fix

// before (Prepare Outgoing Requests script)
return { url, method: 'POST', auth: accessToken };

// after — basic auth as 'username:password'
return { url, method: 'POST', auth: `${user}:${password}` };

// or, for token auth, set the header directly and skip `auth`
return { url, method: 'POST', headers: { Authorization: `Bearer ${accessToken}` } };

Defensive patterns

Strategy: validation

Validate before calling

// inside the integration's Prepare Outgoing Requests script
const basic = `${encodeURIComponent(user)}:${encodeURIComponent(password)}`;
if (!basic.includes(':')) {
  throw new TypeError('auth must be of the form "username:password"');
}
return { url, method: 'POST', auth: basic };

Type guard

const hasUsableAuth = (opts: { auth?: string }): boolean =>
  opts.auth === undefined || (typeof opts.auth === 'string' && opts.auth.includes(':'));

Prevention

Never put raw tokens in opts.auth; use opts.headers.Authorization for Bearer schemes
Build the auth string in one place (`${user}:${password}`) so the separator cannot be lost
Test the Prepare script with a dry-run message and check integration History before relying on the webhook

When it happens

Trigger: An outgoing webhook integration runs a Prepare Outgoing Requests script that returns `{ url, method: 'POST', auth: token }` where token is a bearer/API token (no ':'), or a username without password, or an undefined variable interpolated as e.g. 'undefined'. executeTriggerUrl calls scriptEngine.prepareOutgoingRequest, gets opts.auth without a colon, and throws at triggerHandler.ts:596 before the HTTP call and before history step 'pre-http-call'.

Common situations: Script authors porting curl examples that use `Authorization: Bearer <token>` and assuming the `auth` option accepts tokens; secrets with special characters handled incorrectly; copy-pasted scripts from older Rocket.Chat docs; CI notifications where the password was left empty (`user:` works, but `user` alone does not).

Related errors

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