Troubleshooting Diagram Issues
Solutions for canvas display, performance, and connector behavior.
1. Canvas Fails to Load or Appears Blank
Symptoms
Navigating to /diagram shows a blank white or dark screen without the dot grid.
Resolutions
- Hard Refresh: Press
Cmd + Shift + R(macOS) orCtrl + Shift + R(Windows) to bypass stale browser cache. - Hardware Acceleration: Rekhic's XYFlow canvas utilizes hardware-accelerated rendering. Ensure hardware acceleration is enabled in your browser settings (Chrome:
Settings > System > Use graphics acceleration when available). - Corrupted Local Active Drawing ID: Clear
localStorage.removeItem('activeDrawingId')in your browser console, or open/recentand select a fresh workspace.
2. Connectors Not Snapping to Nodes
Symptoms
Dragging an edge drops into empty space without snapping to the target node.
Cause
Handles appear when hovering close to a node's border. Dragging too quickly past the handle without releasing on the target dot can cause the connection to cancel.
Solution
- Hover over the target node until its blue connection handle highlights.
- Release the mouse directly on the handle.
- Connectors will immediately lock in place and route orthogonally.
3. Nodes Overlapping After Import
Solution
Click the Auto Layout button in the canvas toolbar to automatically recalculate node boundaries and eliminate overlapping boxes.
Next: Troubleshoot export issues in Export Issues.