Troubleshooting

What each thrown error means, how a sync connection ends and why, and the refused status a command returns instead of throwing.

Edytor reports problems three ways: it throws when you misuse an API, a provider reports how a connection ended through events and the document, and a command that cannot apply returns a refused status instead of throwing. This page lists each with its cause and fix.

Thrown errors

Documents lists the document errors with their options.

A block kind no plugin registers does not throw: it renders as a plain block (its text and children) and logs one warning per kind in development. A chord such as cmd+s does not throw either: it fails type-checking and warns in development (chord syntax).

Sync connections

The WebSocket provider reports how a connection ended through its events, and the document keeps a terminal refusal as document.syncRefusal / onSyncRefused. What the client sees depends on the close code:

Before a document has content, a terminal refusal never seeds its value: the document stays pending and document.syncRefusal holds the SyncRefusedError (code, reason). A document that already has content keeps it and stays editable offline.

On the server, room.refusals keeps the newest 100 refusals with their detail and refusalCounts counts them by reason; see diagnostics.

Other provider signals:

• schema-mismatch: an update carrying a foreign schema stamp was dropped; the connection stays.
• protocol-mismatch: a frame of another generation arrived and was dropped.
• document.writable === false: the document holds content from a schema this build cannot own. Every write is refused and providers stop sending until it heals.
• unsaved never reaches 0: the server sends no store acknowledgements (a relay that is not the edytor room). Or it stays above 0 after deleting text a restore lost: the room holds its limit of waiting deletes and dropped this one (a waiting entry in the room’s refusals); the next connection resends it (see the room’s storage). If the limit stays full, dropWaitingDeletes() on the room empties it (a class that uses attachDocument forwards it as its own method: RPC does not reach the returned document).

Refused commands

Editing commands never throw because they cannot apply. They report a status:

• edytor.dispatcher.last.status after a view command: applied, noop (it ran and changed nothing), refused (nothing was written and no undo step recorded) or failed (a hook or the command threw; the error is rethrown and kept in last.error).
• An OpResult from a facade operation: applied, noop or refused, with a reason when the document names one (id-collision).

A command is refused when:

• the view is readonly, or the document is not writable;
• a plugin’s onBeforeOperation called prevent() on the command or on one of its steps;
• the document forbids it: a void block takes no children and never merges or splits, an island’s blocks never leave it and nothing moves into it, a block would sit directly in a list it is no item of (a move or outdent of an image there; see containers), a target is missing or deleted, or an id already exists.

Check last.status after a command you issue when the next step depends on it:

block.setData({ ...block.data, checked: true });
if (edytor.dispatcher.last?.status === 'refused') showReadonlyNotice();

Installing the pre-release