Troubleshooting

This guide covers common issues you may encounter when using the Flowchart App and how to resolve them.

Common Issues

Issue: Canvas Not Rendering

Symptoms:

• The flow editor shows a blank or gray area
• Nodes and edges are not visible
• The minimap is empty

Cause: Usually caused by browser rendering issues or React Flow initialization problems.

Solution:

1. Refresh the page (Ctrl/Cmd + R)
2. If the issue persists, try these steps:

   # Clear your browser cache for the FlowState domain
   # Or use incognito/private browsing mode
   

3. Ensure your browser has hardware acceleration enabled
4. Check the browser console for JavaScript errors

Issue: Nodes Cannot Be Connected

Symptoms:

• Dragging from a handle doesn't create an edge
• Connection line disappears when released
• Edges appear briefly then vanish

Cause: You may be trying to connect incompatible handles or the target node doesn't have the correct handle type.

Solution:

1. Ensure you're dragging from a source handle (right side) to a target handle (left side)
2. Check that both nodes are properly selected and visible
3. Try moving the nodes closer together before connecting
4. Verify the canvas is not in read-only mode (example view)

Issue: Tab Limit Reached

Symptoms:

• "New" button doesn't create a new tab
• Warning message about tab limit
• Unable to open additional flowcharts

Cause: The app has a maximum limit of 10 simultaneously open tabs.

Solution:

1. Close unused tabs by clicking the X on each tab
2. Save any important work before closing tabs
3. Consider consolidating related diagrams

Issue: Nodes Not Appearing from Palette

Symptoms:

• Clicking on a node type in the palette does nothing
• Node palette is unresponsive
• Canvas remains empty after selection

Cause: May be a state synchronization issue or JavaScript error.

Solution:

1. Try clicking a different node type first, then the desired one
2. Refresh the page to reset the component state
3. Check if you have an active tab selected (gray toolbar buttons indicate no active tab)
4. Verify JavaScript is enabled in your browser

Issue: Flowchart Not Saving

Symptoms:

• Changes are lost after page refresh
• Save button appears disabled
• No confirmation after save attempt

Cause: The RxDB data persistence feature is still in development.

Solution:

1. Currently, flowcharts are stored in local memory during the session
2. To preserve your work:
   • Keep the browser tab open
   • Consider taking screenshots of important diagrams
3. Full save/load functionality is coming in a future release

Issue: Minimap Not Showing

Symptoms:

• No minimap visible in the bottom-right corner
• Cannot use minimap for navigation

Cause: The minimap may be hidden or the viewport is too small.

Solution:

1. Ensure your browser window is large enough (minimum 800px width)
2. Check if the canvas has any nodes (empty canvases may not show minimap)
3. Try resizing the browser window to trigger a re-render

Issue: Example Flow Won't Close

Symptoms:

• Close button in example viewer doesn't respond
• Stuck viewing an example flow
• Cannot return to the main interface

Cause: UI state may be out of sync.

Solution:

1. Try clicking the Close button multiple times
2. Press the Escape key
3. Refresh the page to reset the view state

Issue: Performance Lag with Many Nodes

Symptoms:

• Canvas becomes slow to respond
• Pan and zoom are choppy
• Node movement is delayed

Cause: Large diagrams with many nodes and edges can impact performance.

Solution:

1. Split large diagrams into multiple smaller flowcharts
2. Use the minimap for navigation instead of panning
3. Consider closing other browser tabs to free up memory
4. For optimal performance, limit diagrams to ~50 nodes

Issue: Dark/Light Mode Not Applying

Symptoms:

• App doesn't match system theme
• UI elements have unexpected colors

Cause: Theme inheritance from the FlowState container app.

Solution:

1. Theme is controlled by the parent FlowState application
2. Check your FlowState settings for theme preferences
3. The Flowchart App uses the amber (#F59E0B) accent color by design

Browser Compatibility

Note: Internet Explorer is not supported.

Getting Help

If you can't resolve your issue:

1. Check the FAQ for additional answers
2. Review the Features documentation for correct usage
3. Report the issue with the following information:
   • Description of the issue
   • Steps to reproduce
   • Browser name and version
   • Screenshots if applicable
   • Any console errors (press F12 to open developer tools)