RocketChat/Rocket.Chat · error · Meteor.Error

error-authToken-param-not-valid

error-authToken-param-not-valid

Error message

The required "authToken" header param is missing or invalid.

What it means

Thrown as Meteor.Error('error-authToken-param-not-valid', ...) in the POST push.token action when the x-auth-token request header is missing/null. The route declares authRequired:true (so this.userId is set), but the push token registration additionally needs the raw token to hash it via Accounts._hashLoginToken for device binding.

Source

Thrown at apps/meteor/server/api/v1/push.ts:176

					required: ['success', 'result'],
				}),
				400: validateBadRequestErrorResponse,
				401: validateUnauthorizedErrorResponse,
				403: validateForbiddenErrorResponse,
			},
			body: isPushTokenPOSTProps,
			authRequired: true,
		},
		async function action() {
			const { id, type, value, appName, voipToken } = this.bodyParams;

			if (voipToken && !id) {
				return API.v1.failure('voip-tokens-must-specify-device-id');
			}

			const rawToken = this.request.headers.get('x-auth-token');
			if (!rawToken) {
				throw new Meteor.Error('error-authToken-param-not-valid', 'The required "authToken" header param is missing or invalid.');
			}
			const authToken = Accounts._hashLoginToken(rawToken);

			const result = await Push.registerPushToken({
				...(id && { _id: id }),
				token: { [type]: value } as IPushToken['token'],
				authToken,
				appName,
				userId: this.userId,
				...(voipToken && { voipToken }),
			});

			return API.v1.success({ result: cleanTokenResult(result) });
		},
	)
	.delete(
		'push.token',
		{

View on GitHub (pinned to f9d3ec372b)

Solutions

  1. Include both X-User-Id and X-Auth-Token headers on the request (the same pair used for the session).
  2. Verify the header name casing matches (HTTP headers are case-insensitive but the client must send the right name).
  3. Check that the proxy/gateway does not strip x-auth-token.

Example fix

// before
fetch('/api/v1/push.token', { headers: { 'X-User-Id': uid }, body });

// after
fetch('/api/v1/push.token', { headers: { 'X-User-Id': uid, 'X-Auth-Token': rawToken }, body });
Defensive patterns

Strategy: validation

Validate before calling

if (!rawToken) throw new Error('x-auth-token header required');
await fetch('/api/v1/v1/push.token', {
  method: 'POST',
  headers: { 'X-User-Id': uid, 'X-Auth-Token': rawToken, 'Content-Type': 'application/json' },
  body: JSON.stringify({ id, type, value, appName }),
});

Type guard

function hasAuthToken(headers: Record<string,string>): boolean {
  return !!headers['x-auth-token'];
}

Try / catch

null

Prevention

When it happens

Trigger: POST /api/v1/v1/push.token without the x-auth-token header, or with an empty value. The body can be otherwise valid (isPushTokenPOSTProps passes).

Common situations: Mobile/SDK client set X-User-Id but forgot the matching X-Auth-Token header; a proxy stripping the header; the token was stored in a different key than x-auth-token.

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@f9d3ec372b (2026-08-12). Data as JSON: /api/errors/4c38746cbb92ff2c. Report an issue: GitHub.