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

fetchWorkspaceSyncPayload POSTs to {workspaceRegistrationClientUri}/sync with the workspace bearer token; when Cloud answers with a non-2xx status the JSON body's error field is embedded into this CloudWorkspaceConnectionError. The text after the colon is the upstream reason reported by Cloud, not a local message.

Source

Thrown at apps/meteor/server/lib/cloud/syncWorkspace/fetchWorkspaceSyncPayload.ts:28

	data,
}: {
	token: string;
	data: Cloud.WorkspaceSyncRequestPayload;
}): Promise<Cloud.WorkspaceSyncResponse> {
	const workspaceRegistrationClientUri = settings.get<string>('Cloud_Workspace_Registration_Client_Uri');
	const response = await fetch(`${workspaceRegistrationClientUri}/sync`, {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${token}`,
		},
		body: data,
		// 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) {
		const { error } = await response.json();
		throw new CloudWorkspaceConnectionError(`Failed to connect to Rocket.Chat Cloud: ${error}`);
	}

	const payload = await response.json();

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

	if (!result.success) {
		throw new CloudWorkspaceConnectionError('failed type validation', {
			cause: z.prettifyError(result.error),
		});
	}

	return result.data;
}

View on GitHub (pinned to b2c16d5842)

Solutions

1. Read the embedded Cloud error text: unauthorized-style messages mean the stored token is stale — re-register or re-login the workspace
2. Confirm the workspace registration client URL setting points at the official Cloud endpoint and is not rewritten by a proxy
3. If the embedded error indicates a Cloud-side failure, retry the sync later (the job is periodic)
4. Update the Rocket.Chat server if a payload contract change is causing rejections

try {
  await fetchWorkspaceSyncPayload({ token, data: workspaceRegistrationData });
} catch (err) {
  if (err instanceof CloudWorkspaceConnectionError && /unauthorized|forbidden/i.test(err.message)) {
    // token stale: re-register workspace; do not retry with the same token
  } else if (err instanceof CloudWorkspaceConnectionError) {
    // transient upstream failure: let the periodic sync retry later
  } else {
    throw err;
  }
}

When it happens

Trigger: Cloud returns 401/403 because the workspace token was revoked or is stale, 400 because the registration payload is rejected, or any 5xx during a Cloud-side incident — response.ok is false and the body parses as { error }.

Common situations: Workspace re-registered elsewhere so the old token was invalidated; Cloud API temporarily degraded; a TLS-intercepting proxy returning error statuses; version skew between an old server build and the current Cloud API.

Related errors

• App package download failed
• App metadata download failed
• could-not-access-webdav
• Failed to complete OAuth handshake with ${this.name} at ${th
• Failed to connect to Rocket.Chat Cloud: ${error}

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