Troubleshooting

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

Common Issues

Issue: Flowchart Not Rendering

Symptoms:

• Canvas area is blank
• Steps don't appear after selecting a process
• Loading spinner appears indefinitely

Cause: The process may have no steps, or there's a rendering issue with the ReactFlow canvas.

Solution:

1. Refresh the page (Ctrl/Cmd + R)
2. Verify the process has steps defined (new processes start empty)
3. Check if the process is in Draft status with no content
4. Open browser console (F12) and check for JavaScript errors
5. Try zooming out - steps may be positioned off-screen

Issue: Cannot Save Process Changes

Symptoms:

• Save button doesn't respond
• "Saving..." indicator stays indefinitely
• Changes lost after refresh

Cause: Auto-save may have failed due to validation errors or network issues.

Solution:

1. Check for validation errors in the property panel
2. Ensure all required fields are filled:
   • Process must have exactly one Start step
   • Process must have at least one End step
3. Verify network connectivity in browser DevTools
4. Copy any unsaved work as backup
5. Refresh and try editing again
6. Check browser console for specific error messages

Issue: Undo/Redo Not Working

Symptoms:

• Pressing Ctrl/Cmd+Z does nothing
• Undo button is disabled
• Changes not reversing as expected

Cause: Undo stack may be empty, or you're not in edit mode.

Solution:

1. Verify you're in Edit Mode - undo/redo only work when editing
2. Check if the Undo button in the toolbar is enabled (not grayed out)
3. Undo stack clears after saving - previous changes cannot be undone
4. Some actions (like navigating away) clear the undo stack
5. Try using keyboard shortcuts: Ctrl/Cmd+Z for undo, Ctrl/Cmd+Y or Ctrl/Cmd+Shift+Z for redo

Issue: Drag-and-Drop Steps Not Working

Symptoms:

• Steps won't drag from the palette
• Dropping on canvas doesn't create a step
• Cursor shows "not allowed" icon

Cause: Edit mode may not be active, or there's a drag-drop library issue.

Solution:

1. Ensure Edit Mode is enabled (toggle in toolbar)
2. Click and hold on the step type, then drag onto the canvas
3. Make sure you're dropping on the canvas area, not the sidebar
4. Try refreshing the page to reset the drag-drop state
5. Check if another modal or overlay is blocking the canvas

Issue: Cannot Connect Steps

Symptoms:

• Connection lines don't appear when dragging
• Edges disconnect unexpectedly
• Invalid connection error

Cause: Some step types have connection rules, or the handle isn't being detected.

Solution:

1. Drag from the output handle (right side) to the input handle (left/top side)
2. Ensure you're connecting compatible step types:
   • Start steps have only output handles
   • End steps have only input handles
   • Other steps have both input and output handles
3. Decision steps require multiple outgoing connections for branches
4. Make sure the cursor is directly over the target handle (it should highlight)
5. Zoom in for better precision on smaller step nodes

Issue: Subprocess Navigation Not Working

Symptoms:

• Double-clicking subprocess doesn't navigate
• Breadcrumb shows incorrect hierarchy
• Cannot return to parent process

Cause: Subprocess may not have a linked process, or navigation state is corrupted.

Solution:

1. Verify the subprocess step has a process reference configured
2. Open the subprocess step properties and check the linked process
3. Use the breadcrumb to navigate back to any level
4. Click "Home" in the breadcrumb to return to the process list
5. If stuck, manually navigate to /process/processes in the URL

Issue: Publish Button Disabled

Symptoms:

• Publish button is grayed out
• Validation message appears
• Process won't transition to Active status

Cause: Process fails validation requirements.

Solution:

1. Check the publish dialog for specific validation errors:
   • Process must have exactly one Start step
   • Process must have at least one End step
   • All steps must be connected (no orphan steps)
   • Required step properties must be filled
2. Review the validation summary in the dialog
3. Fix any highlighted issues
4. Save the process before attempting to publish
5. Verify the process is in Draft status (already Active processes can't be re-published)

Issue: Approval Step Not Working

Symptoms:

• Cannot configure approvers
• Approval actions don't appear
• Approval status stuck on "Pending"

Cause: Approval configuration may be incomplete, or user doesn't have permissions.

Solution:

1. Verify the approval step has at least one approver configured
2. Check that approval threshold is valid (1 to number of approvers)
3. Ensure you're listed as an approver to see action buttons
4. Verify the approval has been properly initiated during execution
5. Check approval history for any previous actions taken

Issue: Schema Editor Changes Not Saving

Symptoms:

• Field changes disappear after navigating away
• Schema preview doesn't update
• Validation errors persist after fixing

Cause: Schema editor state may be disconnected from the step configuration.

Solution:

1. Make changes in the schema editor and wait for validation
2. Check the validation panel for any remaining errors
3. Click the "Apply" or "Save" button within the schema editor
4. Verify changes appear in the JSON preview
5. Save the overall process to persist schema changes

Issue: Statistics Not Loading

Symptoms:

• Stats page shows loading indefinitely
• Metrics display as zeros or dashes
• Charts don't render

Cause: No execution data exists, or there's a data fetching issue.

Solution:

1. Statistics require process executions to display data
2. If no processes have been executed, stats will be empty
3. Check the time range selector - try switching between 7 and 30 days
4. Verify you have permissions to view execution statistics
5. Refresh the page to re-fetch statistics data
6. Check browser console for API errors

Performance Issues

Issue: Slow Flowchart Rendering

Symptoms:

• Process takes long to load
• Panning and zooming is laggy
• Browser becomes unresponsive

Cause: Large processes with many steps can strain rendering.

Solution:

1. Use subprocesses to break large processes into smaller, manageable pieces
2. Close unused browser tabs
3. Clear browser cache
4. Try using Chrome for best ReactFlow performance
5. Disable browser extensions temporarily
6. Consider archiving unused processes

Issue: High Memory Usage

Symptoms:

• Browser becomes unresponsive after extended use
• Page crashes during editing
• Computer fans run constantly

Cause: ReactFlow and RxDB subscriptions may accumulate in long sessions.

Solution:

1. Refresh the page periodically during long editing sessions
2. Save frequently to commit changes to the database
3. Close the Process App tab when not actively using
4. Use process subprocesses to reduce complexity in single views
5. Avoid keeping many processes open in edit mode

Auto-Layout Issues

Issue: Steps Overlapping After Auto-Layout

Symptoms:

• Steps placed on top of each other
• Connections cross unnecessarily
• Layout looks messy

Cause: The Dagre auto-layout algorithm may struggle with certain graph structures.

Solution:

1. Auto-layout works best with tree-like structures
2. Manual adjustment may be needed after auto-layout
3. Position Start at the top, End at the bottom for best results
4. Complex branching may require manual arrangement
5. Save after manual adjustments to preserve positions

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. Search existing support tickets for similar issues
4. Contact support with:
   • Description of the issue
   • Steps to reproduce
   • Screenshots if applicable
   • Browser version and operating system
   • Any console errors (press F12 to open DevTools)

Collecting Debug Information

When reporting issues, include the following:

1. Browser: [Chrome/Firefox/Safari/Edge] version [X.X]
2. Operating System: [Windows/macOS/Linux] version [X.X]
3. App Version: [Check in app settings or footer]
4. Steps to reproduce:
   a. First step
   b. Second step
   c. ...
5. Expected behavior: [What should happen]
6. Actual behavior: [What actually happens]
7. Console errors: [Copy any red error messages from DevTools]