RocketChat/Rocket.Chat · error · CloudWorkspaceConnectionError

Failed to connect to Rocket.Chat Cloud: ${response.statusTex

Error message

Failed to connect to Rocket.Chat Cloud: ${response.statusText}

What it means

The same non-ok branch in the legacy sync fetch, but the response body is not JSON, so the error falls back to the HTTP statusText. Something other than the cloud API answered the sync request — typically a proxy, a firewall interception page, or a wrong Cloud_Url returning an HTML error.

Source

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

}): 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),
		});
	}

	return result.data;

View on GitHub (pinned to b2c16d5842)

Solutions

  1. From the server, curl the cloud sync endpoint to see the raw response and who produced it.
  2. Allowlist Cloud_Url on proxies/firewalls and exempt it from TLS inspection.
  3. Correct the Cloud_Url setting.
  4. Retry outside maintenance windows and upgrade off the deprecated legacy sync.
Defensive patterns

Strategy: try-catch

Validate before calling

const probe = await fetch(`${cloudUrl}/api/v2/register/workspace/sync`, { method: 'OPTIONS' });
if (!probe.ok && !probe.headers.get('content-type')?.includes('json')) {
  throw new Error('a non-cloud intermediary is answering — fix proxy/Cloud_Url before syncing');
}

Try / catch

try {
  await legacySyncWorkspace();
} catch (e) {
  if (e instanceof CloudWorkspaceConnectionError && /Gateway|Unavailable|Forbidden|Found/.test(e.message)) {
    // infrastructure response, not a cloud app error: inspect proxies and Cloud_Url
  }
  throw e;
}

Prevention

When it happens

Trigger: Proxy/WAF/TLS-inspection interception of the cloud sync request, a misconfigured Cloud_Url served by a generic web server, or gateway 502/503 errors during legacy workspace sync.

Common situations: Corporate egress proxies; Cloud_Url typos; cloud maintenance windows; gateway timeouts returning HTML error pages.

Related errors

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