Once the Document Editor is connected, most problems come from the page around it: a container without a height, code that runs before the editor is ready, or an editor that is created twice in a single-page application. The messages below come from the editor's script and its Angular and React packages. If the editor can't connect in the first place, start with WebSockets. The Document Viewer has no troubleshooting page of its own; its problems follow in the last section.

The Editor Isn't Visible or Has No Height

The page loads, but the editor isn't visible, is only a few pixels high, or doesn't fill its area.

The editor takes the size of its container, and a container without a calculable height has none to give. A height of 100% works only when every parent element has an explicit height as well.

Give the container an explicit height in pixels or with calc(), for example height: calc(100vh - 6rem).
In an ASP.NET Core view, set Dock to DockStyle.Fill, so that the editor fills the container. See Size the Editor.
In Angular, set the width and height attributes, which are required. The React component takes its size from the style prop, 1000 × 800 pixels by default, and the Blazor component from Width and Height, 800 × 600 pixels by default.
If the editor doesn't follow a change of the page layout, call refreshLayout.

The blog article 5 Layout Patterns for Integrating the TX Text Control Document Editor in ASP.NET Core C# shows layouts that size the editor correctly.

TXTextControl.init Throws an Error

On a plain JavaScript page, TXTextControl.init stops with one of these errors:

Container element with id '<id>' not found.
Missing container ID.
Invalid WebSocket URL '<url>'.

init creates the editor in the element named by the ComponentSettings you pass, and connects to the address in their webSocketURL.

Call init after the container element exists, for example at the end of the page or after the DOMContentLoaded event.
Pass the ID of the container as a string in containerID.
Pass a WebSocket address that starts with ws:// or wss://. See The WebSocket URL Is Wrong.

A property name in editorSettings that DocumentEditorSettings doesn't have is reported in the console as Unknown editor settings property and ignored.

The Editor Is Already Initialized

Opening the editor a second time, for example on another route of a single-page application or in a partial view loaded again, fails with:

The editor is already initialized.

There can be only one Document Editor on a page. Routes and partial views don't reload the page, so the first editor is still there. The React component also has no cleanup of its own when it's removed.

Save the document if needed, then call TXTextControl.removeFromDom before the editor's view is removed or the editor is created again. It closes the WebSocket connection and removes the editor from the page.
In Angular, call it in ngOnDestroy. See Use the Editor on Routes.
In React, call it in the cleanup function of useEffect. See Load, Save and Remove the Editor.
On a JavaScript page that loads the editor dynamically, remove the script element as well. See Create and Remove the Editor at Run Time.

Instead of removing the editor, an application can keep one instance and move it between views; the blog article Reuse Persistent Document Editor Components in Angular SPA Applications shows how.

Code Runs Before the Editor Is Ready

A call of the JavaScript API or an event handler fails, and the console shows:

WebSocket connection has not been established yet. Attach TextControl event handlers in the 'textControlLoaded' event or later.

The TXTextControl object exists as soon as the script is loaded, but most of its members work only after the editor has connected. The event textControlLoaded occurs when the editor is ready to be used.

Put the code that uses the API into a handler of textControlLoaded.
In Angular, wait for the event txDocumentEditorLoaded on document; in React, use the onLoad callback; in Blazor, the OnLoad event.
Change a document that is loaded at startup in the documentLoaded event, and the ribbon in ribbonTabsLoaded.

When the Object Is Available explains the order, and Events During Initialization the events. Many methods also take an error callback; see Callbacks.

React Reports That the Element Type Is Invalid

A React application created with Vite 8 fails when it renders the editor or the viewer:

Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

The packages @txtextcontrol/tx-react-document-editor and @txtextcontrol/tx-react-document-viewer are CommonJS modules. Since Vite 8, their default import returns the module object instead of the component in projects whose package.json sets "type": "module", as the Vite templates do.

Import the package under another name and take the component from its default property, as Import the Components in Vite 8 shows. The same applies to the viewer.

Angular or React Asks for a WebSocket URL

The Angular or React component stops with:

Please provide a WebSocket URL.

The webSocketURL attribute or prop is empty. Both components read their settings once, when they're created, so a value that arrives later isn't used.

Pass the WebSocket address of the backend when the component is created.
To change settings of a running editor, use the JavaScript API, for example setEditMode.

WebSockets describes the format of the address.

The C# Methods of the Blazor Editor Throw NullReferenceException

In a Blazor application, LoadDocumentAsync or another C# method of the editor component throws a NullReferenceException.

The C# methods reach the editor's session through the WebSocket middleware in the process of the Blazor application. When WebSocketURL points to another application, that process has no session.

Host the middleware and the backend in the Blazor application itself, as Blazor configures it.
If the editor connects to another application, use the JavaScript API instead of the C# methods.

The Document Editor requires interactive server rendering. A build that fails with NETSDK1082 is covered in Installation.

A Method Fails With the Cross-Platform Backend

setRenderMode throws an error, or a formatting printer set with setFormattingPrinter has no effect.

Both work only with the Windows-based backend of the .NET Framework. The cross-platform backend TXTextControl.Web.Server.Core has only the SVG-based render mode, and it doesn't support printer-specific formatting.

Remove the calls of setRenderMode and setFormattingPrinter, and the formattingPrinter attribute of the Angular and React components.

A Dialog Box Is Missing on Linux

An editor that runs on Linux doesn't offer a built-in dialog box, or its ribbon or context menu has fewer items than on Windows.

Before version 34.0, some dialog boxes were available only in the Windows-based Document Editor. Version 34.0 made all built-in dialog boxes available on Linux and changed the ribbons and context menus so that they work as on Windows.

Update all TX Text Control packages to version 34.0. See Installation.
If your application customizes the ribbon or the context menus, test the customizations after the update.

Misspelled Words Aren't Marked

The editor doesn't underline misspelled words.

Spell checking needs TX Spell .NET, a separate product with its own license, and it must be turned on in the editor.

Install the package TXTextControl.TXSpell.Core.SDK in the application that hosts the Document Editor backend. Its current version is 11.0.1.
Turn spell checking on with setIsSpellCheckingEnabled after textControlLoaded.
Make sure a dictionary for the language of the text is loaded. The package contains the dictionary for US English; the dictionaries of other languages are downloaded separately. See Dictionaries.

Spell Checking describes the setup.

A Document Doesn't Load or Save

loadDocument or saveDocument fails, or the loaded document shows the wrong characters.

The usual causes are:

The editor isn't ready. Call loadDocument in the textControlLoaded handler or later.
The text isn't encoded correctly. The browser's btoa handles only Latin-1 characters. Encode text with TXTextControl.btoaUTF8, which handles all Unicode characters.
The saved data is decoded wrongly. SaveDocumentResult.data is Base64-encoded for binary formats such as PDF and DOCX, and plain text for text formats such as HTML and RTF. A controller that decodes Base64 must store HTML and RTF as text.
The format isn't supported. The Document Editor backend uses the Core engine, which doesn't load or save DOC.

To see the reason of a failure, pass an error callback; its argument has the message in msg. Loading and Saving Documents shows the complete code.

The Document Viewer Doesn't Load

The Document Viewer has the same kinds of problems in its own setup:

The scripts of the viewer return 404 in a Razor Pages application. Both AddControllers and UseTXDocumentViewer are required; MapControllers alone doesn't map the controller of the viewer. Don't name a controller of your own TextControl. See Use Razor Pages.
The viewer doesn't load in Angular, React or JavaScript. Check that the backend is running and that basePath is its address. The viewer uses HTTP requests, so the backend's CORS policy must allow the origin of the frontend. See Configure Program.cs for Separate Frontends.
A protected action of your controller fails with InvalidOperationException. UseTXDocumentViewer runs the endpoints, so it has to come after UseAuthorization.
The Blazor viewer doesn't load its scripts. Omit the trailing slash in BasePath; the component appends the paths of its scripts.
React reports that the element type is invalid. The fix is the same as for the editor, above.

Architecture of the Document Viewer explains its parts.

Document Editor