RocketChat/Rocket.Chat · error · CloudWorkspaceConnectionError

Failed to connect to Rocket.Chat Cloud: ${error}

Error message

Failed to connect to Rocket.Chat Cloud: ${error}

What it means

The deprecated legacy cloud sync (fetchWorkspaceClientPayload) POSTs workspace registration data with the workspace access token as Bearer; a non-ok response with a JSON body becomes CloudWorkspaceConnectionError('Failed to connect to Rocket.Chat Cloud: <cloud error>'). The text after the colon is the cloud's rejection reason — most often an expired or revoked token, or a workspace the cloud no longer recognizes.

Source

Thrown at apps/meteor/server/lib/cloud/syncWorkspace/legacySyncWorkspace.ts:40

	token: string;
	workspaceRegistrationData: WorkspaceRegistrationData<undefined>;
}): Promise<Cloud.WorkspaceSyncPayload | undefined> => {
	const workspaceRegistrationClientUri = settings.get<string>('Cloud_Workspace_Registration_Client_Uri');
	const response = await fetch(`${workspaceRegistrationClientUri}/client`, {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${token}`,
		},
		body: workspaceRegistrationData,
		timeout: 5000,
		// SECURITY: the URL is a default hardcoded value or an envvar/setting set by an admin. It's safe to disable this check.
		ignoreSsrfValidation: true,
	});

	if (!response.ok) {
		try {
			const { error } = await response.json();
			throw new CloudWorkspaceConnectionError(`Failed to connect to Rocket.Chat Cloud: ${error}`);
		} catch (error) {
			throw new CloudWorkspaceConnectionError(`Failed to connect to Rocket.Chat Cloud: ${response.statusText}`);
		}
	}

	const payload = await response.json();

	if (!payload) {
		return undefined;
	}

	const result = Cloud.WorkspaceSyncPayloadSchema.safeParse(payload);

	if (!result.success) {
		throw new CloudWorkspaceConnectionError('Invalid response from Rocket.Chat Cloud', {
			cause: z.prettifyError(result.error),
		});
	}

View on GitHub (pinned to b2c16d5842)

Solutions

  1. Read the wrapped cloud error message for the concrete rejection reason.
  2. Re-register the workspace with the cloud using a fresh registration token (cloud:connectWorkspace).
  3. Verify the workspace still exists in the Rocket.Chat Cloud console.
  4. Upgrade to a current release that uses the non-legacy sync path.
Defensive patterns

Strategy: try-catch

Try / catch

import { CloudWorkspaceConnectionError } from '<cloud errors module>';

try {
  await legacySyncWorkspace();
} catch (e) {
  if (e instanceof CloudWorkspaceConnectionError && e.message.startsWith('Failed to connect to Rocket.Chat Cloud:')) {
    // read the cloud's reason after the colon; expired/revoked tokens require re-registration
  }
  throw e;
}

Prevention

When it happens

Trigger: legacySyncWorkspace runs (the legacy cloud sync path) while the cloud rejects the sync request: token expired or revoked, workspace deleted on the cloud side, or cloud-side processing errors.

Common situations: Older Rocket.Chat versions still using the legacy sync; the workspace was removed in the cloud portal; access token refresh failing for extended periods leaving a stale token.

Related errors

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