Skip to content

Troubleshooting & FAQ

Use this checklist when something feels off. Most responses link back to other chapters for deeper fixes.

Web component isn’t defined

Symptom: The console shows customElements.define… already used or sciflow-editor is not defined.

Fixes:

  1. Import the bundle only once per page. When using bundlers, prefer a single entry point that re-exports @sciflow/editor-start.
  2. If you hot-reload modules, guard the definition: 
    if (!customElements.get('sciflow-editor')) {
  await import('@sciflow/editor-start');
}

Duplicate definitions

Loading the bundle twice on the same page throws NotSupportedError. Ensure that both the demo bundle and your application bundle aren’t included together.

Toolbar icons are blank squares

As of the current release, toolbar icons are bundled as inline SVGs and no external font is required. If you see blank squares, you may be using an older version of @sciflow/editor-start that relied on the Google Fonts CDN. Upgrade to the latest version, which includes all icons in the bundle. See Icons for details.

Paste turns everything into citations

The citation feature only converts clipboard payloads marked with application/x-sciflow-reference. If you see unexpected conversions:

  1. Confirm that your clipboard handler isn’t injecting JSON with { type: 'reference' }.
  2. Update to the latest bundle where paste detection ignores plain text that isn’t tagged as a reference (fix merged via extractDropPayload hardening).

Outline clicks don’t scroll the editor

Call commands.focus() before commands.scrollIntoView() (already built into the custom outline recipe). Focus ensures that browsers actually honor the scroll request.

Equations show as placeholder or raw TeX

Symptom: Math nodes display a placeholder message or raw TeX instead of rendered SVG.

Fix: The math feature is enabled by default, but the host page must load MathJax 4 for equations to render. Add this script tag to your HTML (typically in <head>):

<script defer src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-svg.js"></script>

Without it, equations still save and load correctly; only the visual rendering is deferred.

Registry returns 404

Double-check your .npmrc:

@sciflow:registry=https://gitlab.com/api/v4/projects/75140004/packages/npm/

If you keep the .npmrc elsewhere (e.g., in your CI runner), make sure the path is exported via NPM_CONFIG_USERCONFIG.

Content Security Policy blocks styles or scripts

Symptom: The editor renders but looks unstyled, or the console shows CSP violations like Refused to apply inline style.

Fixes:

  1. SciFlow uses constructed stylesheets for Shadow DOM styling. In modern browsers (Chrome 73+, Firefox 101+, Safari 16.4+), this works without 'unsafe-inline'. On older browsers, you may need style-src 'unsafe-inline' or a nonce.
  2. If you load MathJax from a CDN, add cdn.jsdelivr.net to script-src.
  3. For WebSocket sync, add your sync server to connect-src.

See Browser Compatibility for the full directive list.

CORS errors when loading images or syncing

Symptom: Images don't load, or the sync connection fails with Access-Control-Allow-Origin errors.

Fixes:

  1. Configure your image server or CDN to return Access-Control-Allow-Origin for your application's origin.
  2. For WebSocket connections (Yjs sync), the WebSocket server must accept connections from your origin.
  3. If serving the editor bundle from a different domain, ensure CORS headers are set on that domain too.

Tables look broken or can't be edited

Symptom: Table cells aren't selectable, columns can't be resized, or table markup appears instead of a rendered table.

Fixes:

  1. Ensure the table feature is included in your feature set. If you use a custom features array, add the table feature explicitly.
  2. Table CSS is part of sciflow-editor.css. Verify the stylesheet is loaded.
  3. Column resizing requires pointer events — if you have pointer-events: none on a parent container, it will break table interactions.

ProseMirror DevTools integration

For debugging document state, install the ProseMirror DevTools browser extension. Access the ProseMirror view for debugging:

const editor = document.getElementById('editor');
// Access the underlying ProseMirror EditorView
const view = editor.editorView;
console.log('Current doc:', view.state.doc.toJSON());
console.log('Selection:', view.state.selection.toJSON());

Debug logging

SciFlow logs errors to the console prefixed with [sciflow-editor]:

Message Cause
failed to initialize editor Initialization failure — check for duplicate custom element definitions
dropping invalid link node A cross-reference node has a malformed href or missing target
unable to read supplied CSSStyleSheet Shadow style injection failed — check that your CSS is valid
received invalid doc JSON; falling back to default document The doc property was set to invalid JSON

To inspect plugin state programmatically:

import { PluginKey } from 'prosemirror-state';

const key = new PluginKey('my-plugin');
const state = editor.plugins.getState(key);
console.log('Plugin state:', state);

Collaborative cursors not showing

Symptom: Multiple users are editing but remote cursors or selections are invisible.

Fixes:

  1. Ensure you're using the Yjs sync adapter with awareness enabled on your YjsProvider.
  2. Remote cursor styles require the editor's default CSS. If you override Shadow DOM styles, verify the cursor classes (.yjs-cursor, .yjs-selection) aren't hidden.
  3. Check that the WebSocket connection is active — cursors rely on Yjs Awareness, which needs a live connection.

Schema validation errors on load

Symptom: The editor loads a default empty document instead of your content, with a console error about invalid JSON.

Fixes:

  1. Validate your document JSON against the generated schema: 
    npx nx run @sciflow/schema-prosemirror:generate-schema
    Then compare your JSON against manuscript-snapshot.schema.json.
  2. Common causes: missing required type fields on nodes, invalid attribute values, content that doesn't match the node's content expression.
  3. After schema updates, existing documents may need migration. See Content Import & Export.

Need help?

  1. Review the User Guide sections again.
  2. Check the Developer Guide if you suspect a build issue.
  3. See Browser Compatibility for environment-specific issues.
  4. Still stuck? Capture logs/screenshots and share them with the core team.