MagicDX

Theme

Magic-Editor-X — Troubleshooting ​

Editor is blank / doesn't render ​

  1. Ensure plugin is enabled and you ran npm run build && npm run develop.
  2. Confirm the field exists on the content type (Content-Type Builder).
  3. Open browser DevTools → Console — look for Editor.js errors.
  4. Clear cache: rm -rf .cache dist node_modules/.cache.

"Module not found" on build ​

Usually a peer dep issue:

bash
npm install --legacy-peer-deps

Or explicitly install Vue 3 + VitePress peer:

bash
npm install vue@^3

Real-time collaboration not syncing ​

Check WebSocket connection:

  1. DevTools → Network → WS tab.
  2. You should see /magic-editor-x/ws connection with messages flowing.
  3. If connection fails:
    • Reverse proxy missing Upgrade headers (see nginx example in Installation).
    • Firewall blocking WebSocket.
    • Load balancer not sticky — use Redis REDIS_URL for cross-instance sync.

Image upload fails ​

  • Check Strapi Upload plugin is enabled and configured.
  • Check user has upload permission.
  • File size limit — increase in config:
    typescript
    'magic-editor-x': {
  config: { upload: { sizeLimit: 100 * 1024 * 1024 } },  // 100MB
},

"Cannot read content" after migration ​

Migration converted content wrong:

  1. Back up database BEFORE re-running.
  2. Validate sample records manually — content should be { blocks: [...] } shape.
  3. If data is corrupt, restore backup and re-run migration with --dry-run first.

Live cursors not showing ​

  • Ensure you have >1 user in the same document simultaneously.
  • Check tier limits — Free allows only 2 editors.
  • Check WebSocket connection is active (see above).
  • Presence data is broadcast every 100ms; if the user is idle, their cursor may not update.

Content saves but doesn't render in frontend ​

Check JSON structure:

bash
curl http://localhost:1337/api/articles/1 | jq '.data.attributes.content'

You should see { blocks: [...], time: ..., version: ... }. If instead you see a string, the migration hasn't happened yet.

Block save errors ​

"Cannot save block — invalid data". Common cause: custom block's save() method returning undefined. Ensure it returns a plain object matching your registered schema.

Performance — editor lags ​

  • Too many blocks (>500 in one document). Split into multiple documents or implement pagination.
  • Heavy browser extensions (Grammarly, LastPass) — disable for Strapi admin.
  • Try the latest Chrome/Firefox — edge cases in older Safari.

Y.js conflict "Tr already been destroyed" ​

Network dropped mid-transaction. Reload the page to restart the sync.

Version history empty ​

  • Advanced tier auto-saves create versions every 5 seconds.
  • Check license is activated (Premium/Advanced).
  • Verify database table magic_editor_x_versions exists.

Enable debug mode ​

bash
DEBUG=magic-editor-x:* npm run develop

Plus browser DevTools → Console for client-side errors.

Still stuck? ​