Troubleshooting MoonEdit: Common Issues and Quick FixesMoonEdit is a lightweight, real-time collaborative text editor designed for minimal latency and straightforward peer-to-peer editing. Though simple, users — especially those running custom setups or using less common networks — can run into issues. This article covers common MoonEdit problems, step-by-step diagnostics, and tested fixes to get you back to editing quickly.
Overview of typical problem areas
- Connection and networking problems (can’t connect, frequent disconnects)
- Latency, lag, or edit conflicts (slow updates, inconsistent document state)
- Authentication and access (passwords, multiple rooms)
- File handling and persistence (saving, exporting, lost changes)
- Compatibility and environment (OS-specific issues, browser vs native clients)
- UI/UX oddities (cursor problems, rendering glitches)
1) Connection and networking problems
Symptoms
- Unable to connect to a MoonEdit server/room.
- Repeated disconnects or “connection lost” messages.
- Peers show offline while they are online.
Checks
- Verify server address and port are correct.
- Confirm the server is running and reachable (ping or telnet to the port).
- Check firewall rules on both client and server.
- If using NAT or behind a router, ensure port forwarding or UPnP is configured.
- For WebSocket-based deployments, ensure HTTP/HTTPS vs WS/WSS protocols match your site’s TLS configuration.
Quick fixes
- Restart the MoonEdit server and clients.
- If connecting over the internet, temporarily disable local firewalls to isolate the issue.
- Use telnet or nc to test the server port:
telnet your-moonedit-host.example 5555 - If behind NAT, forward the MoonEdit port (default often 5555) to the server’s LAN IP.
- Switch to WSS (secure WebSocket) if your site uses HTTPS — mixed content blocks may prevent WS connections.
When to dig deeper
- Intermittent disconnects across multiple clients often indicate network instability, overloaded server, or resource limits (file descriptors, concurrent sockets). Check server logs and system metrics.
2) Latency, lag, or edit conflicts
Symptoms
- Edits appear with delay.
- Out-of-order text or temporary inconsistent document states.
- Overlapping edits from multiple users create conflicts that don’t resolve cleanly.
Checks
- Measure round-trip time (ping) between clients and server.
- Check server CPU, memory, and network usage.
- Ensure the server isn’t swapping or hitting ulimits.
Quick fixes
- Reduce server load: close unused rooms or increase server resources (CPU/RAM).
- If possible, host the server closer to your collaborators (lower network latency).
- Increase the frequency of synchronization (if configurable) to reduce visible lag.
- Restart the server to clear transient resource exhaustion.
When to dig deeper
- If conflict resolution algorithms (CRDT/OT) appear to fail regularly, verify that all clients are using compatible client versions and the server supports the expected protocol version.
3) Authentication and access
Symptoms
- “Wrong password” or inability to join a room.
- Users unintentionally kicked or unable to create rooms.
Checks
- Confirm the exact room name and password (case-sensitive).
- Verify server-side configuration for authentication modules or plugins.
- Check for client version mismatches that might affect authentication protocol.
Quick fixes
- Recreate the room with a simple password temporarily to test.
- Reset or remove the room password to confirm access works without auth.
- Update clients and server to compatible versions.
- Inspect server logs for authentication errors and adjust configuration accordingly.
4) File handling and persistence
Symptoms
- Saved files are empty, incomplete, or missing recent edits.
- Exported documents lack formatting or show errors.
Checks
- Verify the server’s save/export path and write permissions.
- Check whether autosave is enabled and how frequently it runs.
- Confirm that the client is correctly issuing save commands and receiving success messages.
Quick fixes
- Ensure the server process has write permission to the directory used for saves.
- Manually export the document from a stable client session.
- Increase autosave frequency or trigger manual saves before disconnecting.
When to dig deeper
- If saved documents are consistently truncated, check disk space and server-side process limits; run fsck if the filesystem shows errors.
5) Compatibility and environment-specific issues
Symptoms
- Client behaves differently on Windows vs macOS vs Linux.
- Browser client has features missing compared to native apps.
Checks
- Verify supported platforms and recommended browsers.
- Check client logs/JS console in the browser for errors.
- Confirm any native client dependencies or runtime versions (e.g., Node.js).
Quick fixes
- Use a recommended browser (latest Chrome or Firefox) for the most consistent WebSocket support.
- Update OS packages and runtimes required by native clients.
- Clear browser cache and local storage for the MoonEdit site to remove stale state.
6) UI/UX oddities
Symptoms
- Cursor positions not updating correctly.
- Color/author highlights missing or inconsistent.
- Text rendering glitches.
Checks
- Look at client console for rendering or JS errors.
- Confirm theme or CSS overrides aren’t interfering.
- Ensure multiple clients aren’t using conflicting display plugins.
Quick fixes
- Reload the page or restart the client to resync UI state.
- Disable custom themes or browser extensions (e.g., adblockers) that may modify DOM/CSS.
- If using a native client, try the Web client to see if the issue persists.
7) Logs and diagnostic commands (practical checklist)
- Tail server logs while reproducing the issue:
tail -f /var/log/moonedit/server.log - Check open sockets and listening ports:
ss -ltnp | grep moonedit - Check process resource usage:
top -b -n1 | head -n20 - Inspect browser console (Ctrl+Shift+J / Cmd+Option+J) and copy errors.
8) Backups and recovery best practices
- Enable frequent autosave and keep periodic snapshots.
- Export documents before major server updates.
- Use versioned backups (timestamped files) rather than overwriting a single file.
- Test your recovery process periodically by restoring a snapshot to a staging instance.
9) When to ask for help — what to include
Provide:
- Exact MoonEdit version (server and client).
- OS and browser (with versions).
- Server logs around the time the issue occurred.
- Steps to reproduce the issue and expected vs actual behavior.
- Any recent changes (config updates, network changes).
10) Example troubleshooting scenarios
Scenario A — “I can’t connect from remote but LAN works”
- Likely NAT/firewall. Confirm port forwarding, test with nc/telnet, and check ISP blocking.
Scenario B — “Document lost after a crash”
- Check autosave files and server save directory; restore from the latest timestamped snapshot; implement more frequent autosaves and off-server backups.
Scenario C — “Cursors jump or text repeats”
- Likely synchronization/CRDT client mismatch. Ensure all clients are same version and restart them; examine logs for OT/CRDT errors.
Final notes
Keep MoonEdit components updated, run the server on a stable host with sufficient resources, and maintain regular backups. Most issues resolve by checking connectivity, permissions, and matching client/server versions; when they don’t, server logs and precise reproduction steps will speed any external help you request.
Leave a Reply