Real-time Collaboration: Add sync connection error handling by shekharnwagh · Pull Request #74075 · WordPress/gutenberg

shekharnwagh · 2025-12-17T18:21:39Z

What?

Add sync connection error handling

Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users.

Why?

Sync providers currently have no standard way to communicate connection errors to users. When a sync provider disconnects or authentication fails, users are left in an unclear state with no feedback about what happened or how to save their work.

This PR provides a centralized system for any sync provider to report connection status and automatically display a modal to users when disconnections occur.

How?

This implementation is based on the modal from the VIP Real-Time Collaboration plugin:
https://github.com/Automattic/vip-real-time-collaboration/blob/trunk/src/components/post-locked-modal.tsx

Added a new Redux store (core/sync-connection) in @wordpress/sync package that tracks connection status for all sync providers
Created SyncConnectionModal component in @wordpress/block-editor that displays when any provider reports a disconnection
Providers can call setConnectionStatus() with standard error types (auth failed, too many connections, etc.) or custom messages
Modal provides users with options to copy their content and safely exit the editor

github-actions · 2025-12-17T18:22:21Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @shekharnwagh! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

chriszarate · 2025-12-19T19:08:35Z

This PR provides a centralized system for any sync provider to report connection status and automatically display a modal to users when disconnections occur.

Great work so far! My two main comments are:

The sync package should remain narrowly focused on orchestrating the syncing and transport; this feels like an expansion of that scope that we should avoid if we can.
The core-data package uses the sync package to make its data "sync-enabled." Other packages within Gutenberg should ideally be completely agnostic to if or how data is being synced.

Instead of a new store within sync, I think we can enhance the ProviderCreator interface to provide the entrypoint we need, then manage the resulting state elsewhere. It could look something like this:

export type ProviderCreator = (
	objectType: ObjectType,
	objectId: ObjectID | null,
	ydoc: Y.Doc,
	onStateChange: ( newState: ConnectionState ) => void
) => Promise< ProviderCreatorResult >;

The provider is expected to call the onStateChange fn that it is passed. There is no need for the provider to import additional code and the ConnectionState stays associated with the entity instead of an abitrary connection ID.

As for subscribing to these state changes in the block editor, I thought about the following options:

Introduce new root-level state, selectors, and actions in the core-data store for sync connection states. This makes some sense because (a) the core-data store already manages all of the entity-related state for the block editor; (b) the core-data package creates the SyncManager instance and calls its lifecycle methods as needed; and (c) the block-editor already subscribes to state from core-data when it needs entity-related data.
- In this case, the getEntityRecord resolver in core-data defines the onStateChange callback as passes it to SyncManager.load() as a new RecordHandler. Then it is simply passed through to the provider. In that callback, it would dispatch the necessary actions to update state in the core-data store.
- A selector used by the block-editor would need to accept some kind of entity identifier (e.g., postType, postId) and be able to map it to however the connection state is indexed in core-data's store (e.g., objectType, objectId).
- The block-editor no longer needs to import sync—or be sync-aware at all, really, which should be our goal.
Make syncConnectionState a new transient property on the entity itself. No new RecordHandler is needed; the sync manager can just call the existing editEntityRecord handler whenever the connection state changes.
- Similarly, no new state or selectors are needed in core-data since the data is available on the entity itself.
- IMO, this option is more likely to raise objections with others because the property is "synthetic." If you like this option, you should probably get some feedback from other contributors before proceeding.

I also want to make sure our approach is ready to work with multiple entities! If we have loaded a post entity, a notes collection, and a template entity for syncing, how do we communicate the connection states of all three? What triggers the modal: a single connection error or multiple errors? If multiple, how many? Should a connection state error for a one enetity disrupt the ability to continue working with others that are still connected? Mapping this out now will help light the path.

shekharnwagh · 2026-01-07T16:56:26Z

@chriszarate Thank you for the review and suggestions!

Instead of a new store within sync, I think we can enhance the ProviderCreator interface to provide the entrypoint we need, then manage the resulting state elsewhere.

Moved this to being managed in core-data under the key syncConnectionStates with the room name as key and the connection state as value with following shape:

interface SyncConnectionState {
	status: 'connected' | 'disconnected';
	errorType?: 'auth-failed' | 'too-many-connections' | 'connection-expired' | 'custom' | string;
	title?: string; // Optinal custom title for the modal
	description?: string; // Optional custom description for the modal
}

I also want to make sure our approach is ready to work with multiple entities! If we have loaded a post entity, a notes collection, and a template entity for syncing, how do we communicate the connection states of all three? What triggers the modal: a single connection error or multiple errors? If multiple, how many? Should a connection state error for a one enetity disrupt the ability to continue working with others that are still connected? Mapping this out now will help light the path.

This structure maintains the connection state on a per-entity basis, making it suitable for handling multiple entities at once. At present, the modal is shown for the first entity that reports a disconnected state. This helps avoid situations where, for example, a meta field fails to sync but the user perceives the post as syncing successfully, potentially causing confusion. In most cases, issues that trigger the modal might be server connection errors, authentication failures, or sync limits which are likely unrelated to any specific entity and would affect all entities being synced. But if we can think of cases where an error might be entity specific, we can look into options on how to handle this.

chriszarate · 2026-01-07T18:44:11Z

But if we can think of cases where an error might be entity specific, we can look into options on how to handle this.

I'm thinking mostly of connection errors that only affect 1 entity because of an n + 1 problem like a connection limit.

shekharnwagh · 2026-01-08T11:14:38Z

But if we can think of cases where an error might be entity specific, we can look into options on how to handle this.

I'm thinking mostly of connection errors that only affect 1 entity because of an n + 1 problem like a connection limit.

I'm inclined to show the modal even if a single entity encounters connection issues. This would ensure atomic behavior, where the sync either completes entirely or not at all, unless the issue is specific to a particular entity and due to sync server like auth, connection limit, etc.

chriszarate · 2026-01-08T16:37:06Z

packages/editor/src/components/sync-connection-modal/index.js

+} from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+import { error as errorIcon } from '@wordpress/icons';
+import { getConnectionStatusMessage } from '@wordpress/sync';


It would be nice not to import the sync package at all and continue to rely purely on core-data.

Is there a better pattern than translating codes to user-ready text? I see from core-data/src/selectors.js that there are many examples of Error objects in state. Errors have a message property and could also provide a data property for additional context.

I moved the sync package dependency by moving the util to editor package. I went with using plain objects instead of Error object to keep it simple (no having create an instance and then attach additional fields). What would be other upside of using Error instances ?

packages/sync/src/types.ts

alecgeatches · 2026-01-08T21:02:22Z

@shekharnwagh Thank you for working on this! Error results overlap with a problem I'm working on over in add/rtc-version-check, where I'd like to disconnect a user when another user joins with a newer CRDT_STATE_VERSION_KEY. That PR itself is a requirement for the add/flattened-rtc-blocks branch where the data structure for the Y.Doc changes and we want to disconnect clients still using an older version.

Anyway, I'd like to understand if/how I can propagate an error when a version change is detected using your code in this branch. In my current version of the code, I call unload() when an old version is detected:

const onStateUpdate = createVersionObserver( ydoc, () => {
    // Disconnect providers when outdated client is detected
    unload();
} );

This sort of works, but our websocket client interprets the unload() as a connection-close, then proceeds to open up the connection again, so the old client just reconnects to the post after seeing the disconnect dialog briefly.

I need some way instead of unload() to indicate to the provider that there's an unrecoverable connection-error (or similar) but it's not actually generated from the provider like a token mismatch. Does this PR give me any escape hatch to propagate an unrecoverable error myself inside of entity logic?

chriszarate · 2026-01-09T02:45:41Z

I need some way instead of unload() to indicate to the provider that there's an unrecoverable connection-error (or similar) but it's not actually generated from the provider like a token mismatch. Does this PR give me any escape hatch to propagate an unrecoverable error myself inside of entity logic?

@alecgeatches You can call provider.destroy() then call the onStateChange handler with the error you want.

Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

alecgeatches · 2026-01-21T17:38:29Z

The failing test in this PR Playwright - 1 has been marked as flaky and has a lot of recent failures. It doesn't seem to be related to any changes here, and test artifacts show nothing related to this PR. The test also passes locally in testing. Based on all that, I'm planning to merge this and ignore the failure.

…s#74075) * Add sync connection error handling Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users. * Consolidate sync connection state into core-data Removes the separate syncConnectionStore and moves connection state management into core-data. Sync providers now receive an onStateChange callback to report connection status for both entities and collections. * Remove sync package dependency from editor Moves sync error message handling from @wordpress/sync into editor utils. * Use event emitter pattern for provider status events Replace callback injection with event listener pattern for reporting provider connection status. Providers now expose an on() method that allows attaching listeners after creation, rather than receiving callbacks as constructor parameters. * Document sync provider connection state types Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

…74075) * Add sync connection error handling Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users. * Consolidate sync connection state into core-data Removes the separate syncConnectionStore and moves connection state management into core-data. Sync providers now receive an onStateChange callback to report connection status for both entities and collections. * Remove sync package dependency from editor Moves sync error message handling from @wordpress/sync into editor utils. * Use event emitter pattern for provider status events Replace callback injection with event listener pattern for reporting provider connection status. Providers now expose an on() method that allows attaching listeners after creation, rather than receiving callbacks as constructor parameters. * Document sync provider connection state types Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

…s#74075) * Add sync connection error handling Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users. * Consolidate sync connection state into core-data Removes the separate syncConnectionStore and moves connection state management into core-data. Sync providers now receive an onStateChange callback to report connection status for both entities and collections. * Remove sync package dependency from editor Moves sync error message handling from @wordpress/sync into editor utils. * Use event emitter pattern for provider status events Replace callback injection with event listener pattern for reporting provider connection status. Providers now expose an on() method that allows attaching listeners after creation, rather than receiving callbacks as constructor parameters. * Document sync provider connection state types Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

…74075) * Add sync connection error handling Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users. * Consolidate sync connection state into core-data Removes the separate syncConnectionStore and moves connection state management into core-data. Sync providers now receive an onStateChange callback to report connection status for both entities and collections. * Remove sync package dependency from editor Moves sync error message handling from @wordpress/sync into editor utils. * Use event emitter pattern for provider status events Replace callback injection with event listener pattern for reporting provider connection status. Providers now expose an on() method that allows attaching listeners after creation, rather than receiving callbacks as constructor parameters. * Document sync provider connection state types Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

…s#74075) * Add sync connection error handling Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users. * Consolidate sync connection state into core-data Removes the separate syncConnectionStore and moves connection state management into core-data. Sync providers now receive an onStateChange callback to report connection status for both entities and collections. * Remove sync package dependency from editor Moves sync error message handling from @wordpress/sync into editor utils. * Use event emitter pattern for provider status events Replace callback injection with event listener pattern for reporting provider connection status. Providers now expose an on() method that allows attaching listeners after creation, rather than receiving callbacks as constructor parameters. * Document sync provider connection state types Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

…74075) * Add sync connection error handling Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users. * Consolidate sync connection state into core-data Removes the separate syncConnectionStore and moves connection state management into core-data. Sync providers now receive an onStateChange callback to report connection status for both entities and collections. * Remove sync package dependency from editor Moves sync error message handling from @wordpress/sync into editor utils. * Use event emitter pattern for provider status events Replace callback injection with event listener pattern for reporting provider connection status. Providers now expose an on() method that allows attaching listeners after creation, rather than receiving callbacks as constructor parameters. * Document sync provider connection state types Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

…s#74075) * Add sync connection error handling Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users. * Consolidate sync connection state into core-data Removes the separate syncConnectionStore and moves connection state management into core-data. Sync providers now receive an onStateChange callback to report connection status for both entities and collections. * Remove sync package dependency from editor Moves sync error message handling from @wordpress/sync into editor utils. * Use event emitter pattern for provider status events Replace callback injection with event listener pattern for reporting provider connection status. Providers now expose an on() method that allows attaching listeners after creation, rather than receiving callbacks as constructor parameters. * Document sync provider connection state types Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

* Real-time collaboration: Add sync connection error handling (#74075) * Add sync connection error handling Creates a provider-agnostic system for sync providers to report connection errors and display appropriate UI to users. * Consolidate sync connection state into core-data Removes the separate syncConnectionStore and moves connection state management into core-data. Sync providers now receive an onStateChange callback to report connection status for both entities and collections. * Remove sync package dependency from editor Moves sync error message handling from @wordpress/sync into editor utils. * Use event emitter pattern for provider status events Replace callback injection with event listener pattern for reporting provider connection status. Providers now expose an on() method that allows attaching listeners after creation, rather than receiving callbacks as constructor parameters. * Document sync provider connection state types Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus. * Real-time collaboration: Add provider 'connecting' status (#74826) * Real-time collaboration: Update sync provider event name and modal handling (#74904) * Rename sync provider status event to prevent conflicts Renamed the event from 'status' to 'sync-connection-status' to make it unique and avoid conflicts. This ensures sync-specific connection state events are distinct from generic provider status events. * Show sync disconnection modal for all disconnect states Previously, the modal only appeared when connectionState.error existed. This meant users might be disconnected without seeing any indication if the disconnection didn't include a specific error object. * Real-time collaboration: Add connection status events to HTTP polling provider Adds event emitter to HTTP polling provider to report connection state changes. When the provider connects or disconnects, it emits sync-connection-status events that update core-data and trigger the disconnection modal for users. * Real-time collaboration: Improve sync connection modal with debounce Debounces initial modal display by 5s to prevent flicker during page load. Updates selector to return all connection statuses and makes onStatusChange callback mandatory for consistent error handling * Fix the handler issue in manager * Import BlockCanvasConver from private API * Restore return annotation * Fix useSelect comparison warning * Simplify implementation to onStatusChange * Remove getSyncErrorMessages export * Fix type * Fix serialize performance issue * Fix resolver test --------- Co-authored-by: Alec Geatches <alec.geatches@automattic.com> Co-authored-by: ingeniumed <ingeniumed@users.noreply.github.com> Co-authored-by: chriszarate <chris.zarate@automattic.com>

github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Dec 17, 2025

ingeniumed added [Feature] Real-time Collaboration Phase 3 of the Gutenberg roadmap around real-time collaboration [Type] Experimental Experimental feature or API. labels Dec 18, 2025

ingeniumed changed the title ~~Add sync connection error handling~~ Real-time Collaboration: Add sync connection error handling Dec 18, 2025

shekharnwagh force-pushed the add/sync-provider-disconnection-modal branch from 819e8cf to 8d92d45 Compare January 7, 2026 11:20

github-actions bot added [Package] Core data /packages/core-data [Package] Editor /packages/editor [Package] Sync labels Jan 7, 2026

shekharnwagh force-pushed the add/sync-provider-disconnection-modal branch 3 times, most recently from 1f267a3 to ec9f334 Compare January 7, 2026 12:42

chriszarate reviewed Jan 8, 2026

View reviewed changes

packages/sync/src/types.ts Show resolved Hide resolved

shekharnwagh force-pushed the add/sync-provider-disconnection-modal branch 2 times, most recently from af3e249 to 33f31ec Compare January 12, 2026 10:33

alecgeatches mentioned this pull request Jan 12, 2026

Real-time collaboration: Add CRDT_STATE_VERSION_KEY check #74561

Draft

ingeniumed force-pushed the wpvip/rtc-plugin branch from 9d00f34 to 7b467e1 Compare January 14, 2026 10:45

shekharnwagh force-pushed the add/sync-provider-disconnection-modal branch from 1da843a to e4ebef9 Compare January 14, 2026 17:26

github-actions bot added [Package] Block editor /packages/block-editor [Package] E2E Tests /packages/e2e-tests [Package] Edit Site /packages/edit-site [Package] DataViews /packages/dataviews [Package] Fields /packages/fields labels Jan 14, 2026

chriszarate approved these changes Jan 20, 2026

View reviewed changes

Document sync provider connection state types

7009246

Adds JSDoc to OnStateChangeCallback, ProviderCreatorOptions, SyncConnectionError, SyncConnectionState, and SyncConnectionStatus.

shekharnwagh force-pushed the add/sync-provider-disconnection-modal branch 3 times, most recently from 2e0be8c to 7009246 Compare January 21, 2026 17:17

alecgeatches merged commit 61eab34 into WordPress:wpvip/rtc-plugin Jan 21, 2026
112 of 116 checks passed

alecgeatches deleted the add/sync-provider-disconnection-modal branch January 21, 2026 17:38

alecgeatches mentioned this pull request Jan 21, 2026

Update createWebSocketConnection function signature Automattic/vip-real-time-collaboration#143

Merged

shekharnwagh mentioned this pull request Jan 29, 2026

Real-time collaboration: Add sync connection status handling #75066

Merged

maxschmeling mentioned this pull request Feb 10, 2026

Real-time Collaboration: Fix error when collaboratorInfo is null #75401

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Real-time Collaboration: Add sync connection error handling#74075

Real-time Collaboration: Add sync connection error handling#74075
alecgeatches merged 5 commits intoWordPress:wpvip/rtc-pluginfrom
Automattic:add/sync-provider-disconnection-modal

shekharnwagh commented Dec 17, 2025

Uh oh!

github-actions bot commented Dec 17, 2025

Uh oh!

chriszarate commented Dec 19, 2025

Uh oh!

shekharnwagh commented Jan 7, 2026

Uh oh!

chriszarate commented Jan 7, 2026

Uh oh!

shekharnwagh commented Jan 8, 2026

Uh oh!

chriszarate Jan 8, 2026

Uh oh!

shekharnwagh Jan 9, 2026

Uh oh!

Uh oh!

alecgeatches commented Jan 8, 2026

Uh oh!

chriszarate commented Jan 9, 2026

Uh oh!

alecgeatches commented Jan 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

shekharnwagh commented Dec 17, 2025

What?

Why?

How?

Uh oh!

github-actions bot commented Dec 17, 2025

Uh oh!

chriszarate commented Dec 19, 2025

Uh oh!

shekharnwagh commented Jan 7, 2026

Uh oh!

chriszarate commented Jan 7, 2026

Uh oh!

shekharnwagh commented Jan 8, 2026

Uh oh!

chriszarate Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

shekharnwagh Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alecgeatches commented Jan 8, 2026

Uh oh!

chriszarate commented Jan 9, 2026

Uh oh!

alecgeatches commented Jan 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants