Troubleshooting

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

Product Management Issues

Issue: Product Creation Wizard Loses Progress

Symptoms:

• Wizard closes unexpectedly
• Progress through wizard steps is lost
• Cannot complete product creation

Cause: Session storage may have been cleared or browser settings prevent storage.

Solution:

1. Ensure your browser allows session storage
2. Complete the wizard in a single session without closing the browser
3. If progress is lost, start the wizard again - drafts are not auto-saved
4. Consider drafting your product information (name, description, value proposition) before starting the wizard

Issue: Cannot Edit Product Information

Symptoms:

• Edit button does not respond
• Changes not saving
• Form validation errors persist

Cause: May be a permissions issue or data validation failure.

Solution:

1. Verify you have edit permissions for this product (Owner or Contributor role)
2. Check all required fields are completed:
   • Product name (required)
   • Product type (required)
3. Ensure text fields don't exceed character limits
4. Try refreshing the page and editing again

Issue: Product Not Appearing in List

Symptoms:

• Newly created product not visible
• Product disappeared from list
• Search returns no results

Cause: Filters may be hiding the product, or sync issue occurred.

Solution:

1. Clear all filters by clicking "Reset Filters"
2. Check the lifecycle phase filter - your product may be in a different phase
3. Check the product type filter
4. Refresh the page to sync latest data
5. Verify you're in the correct organization/workspace

Goals & OKR Issues

Issue: Goal Progress Not Updating

Symptoms:

• Progress bar stuck at 0%
• Metrics not reflecting in goal progress
• Manual progress updates not saving

Cause: Progress mode may be set incorrectly or metrics are not properly configured.

Solution:

1. Check the goal's progress mode:
   • Manual: You must manually update the progress percentage
   • Automatic: Progress is calculated from linked metrics
2. For automatic mode, ensure metrics have:
   • A start value
   • A target value
   • A current value
3. Save changes after updating metric values

Issue: Cannot Create Child Goals

Symptoms:

• Parent goal dropdown is empty
• Goal hierarchy not working
• Child goal not appearing under parent

Cause: Parent goals may not exist or may be filtered out.

Solution:

1. Ensure parent goals exist before creating child goals
2. Create top-level goals first, then add children
3. Check that the parent goal belongs to the same product
4. Verify the parent goal is not in "Complete" status (completed goals cannot accept new children)

Issue: Goal Charts Not Displaying

Symptoms:

• Dashboard view shows empty charts
• "No data" message appears
• Charts load indefinitely

Cause: Insufficient data or rendering issue.

Solution:

1. Ensure you have at least one goal created
2. Goals need metrics attached for some charts to display
3. Try switching to List view and back to Dashboard
4. Clear browser cache and reload
5. Try a different browser to rule out compatibility issues

Roadmap Issues

Issue: Cannot Drag Initiatives

Symptoms:

• Drag-and-drop not working
• Initiative card doesn't move
• Drop zone not highlighting

Cause: Browser compatibility or touch device without proper support.

Solution:

1. Use a desktop browser (Chrome, Firefox, Safari, or Edge)
2. Click and hold for a moment before dragging
3. Ensure you're dragging from the initiative card body, not the action buttons
4. Try refreshing the page if drag-and-drop stops working
5. On touch devices, use the edit modal to change quarter/status instead

Issue: Initiatives Not Saving to Correct Quarter

Symptoms:

• Initiative appears in wrong quarter after save
• Quarter assignment reverts
• Drag-and-drop moves to unexpected location

Cause: Year navigation may be out of sync or quarter format issue.

Solution:

1. Check the year navigator - ensure you're viewing the correct year
2. When creating initiatives, verify the quarter format (Q1, Q2, Q3, Q4)
3. The quarter is relative to the selected year
4. Edit the initiative manually if drag-and-drop produces unexpected results

Issue: Projects Not Linking to Initiatives

Symptoms:

• Project link modal shows no projects
• Linked projects not appearing on initiative
• Cannot remove project links

Cause: No projects exist or organization mismatch.

Solution:

1. Create projects in the Projects App first
2. Ensure projects belong to the same organization
3. Check that projects are not already linked to other initiatives
4. Refresh the modal if project list appears empty

Team & RACI Issues

Issue: Cannot Add Team Members

Symptoms:

• User search returns no results
• Add member button disabled
• Team member not appearing after adding

Cause: User may not exist in the organization or already a team member.

Solution:

1. Search by email or full name
2. Verify the user exists in your FlowState organization
3. Check if the user is already a team member (duplicates not allowed)
4. Request the user be invited to the organization if not found

Issue: RACI Matrix Not Saving

Symptoms:

• RACI assignments disappear after refresh
• Click on cell doesn't cycle through roles
• Warning indicators persist despite assignments

Cause: Data sync issue or validation failure.

Solution:

1. Click cells slowly - each click cycles through R, A, C, I, and empty
2. Wait for the save indicator before navigating away
3. Ensure RACI areas are created before assigning roles
4. Refresh and re-check if assignments persist
5. Check the console for error messages (F12 > Console tab)

Issue: RACI Validation Warnings Won't Clear

Symptoms:

• "Missing Accountable" warning persists
• "Missing Responsible" warning persists
• Warnings show for areas that have assignments

Cause: RACI rules require exactly one Accountable per area.

Solution:

1. Each RACI area must have:
   • Exactly one person marked as Accountable
   • At least one person marked as Responsible
2. Review the matrix to ensure every area has these assignments
3. If multiple people are marked as Accountable for the same area, change one to a different role

Portfolio & Dashboard Issues

Issue: Portfolio Health Indicators Incorrect

Symptoms:

• Health status shows wrong color (red/yellow/green)
• Health doesn't reflect actual product status
• All products show same health indicator

Cause: Health is calculated from goal statuses which may not be updated.

Solution:

1. Health is calculated based on goal status percentages:
   • Green: Most goals On Track or Complete
   • Yellow: Some goals At Risk
   • Red: Many goals At Risk or overdue
2. Update goal statuses to reflect current reality
3. Ensure goals have metrics with current values
4. Add goals to products that show "No data" for health

Issue: Activity Feed Empty

Symptoms:

• Activity tab shows no entries
• Recent changes not appearing
• Filter returns no results

Cause: Activities may be filtered or not yet recorded.

Solution:

1. Clear activity filters to show all entries
2. Activities are recorded for major actions (create, update, delete)
3. Minor edits may not generate activity entries
4. Check the date range if using date filters

Browser & Performance Issues

Issue: App Loads Slowly

Symptoms:

• Long loading times
• Spinner appears frequently
• UI feels unresponsive

Cause: Large dataset, network issues, or browser resource constraints.

Solution:

1. Use filters to reduce the amount of data displayed
2. Close unnecessary browser tabs
3. Clear browser cache
4. Check your network connection
5. Use pagination for large lists

Issue: Offline Changes Not Syncing

Symptoms:

• Changes made offline not appearing after reconnecting
• Sync indicator shows error
• Duplicate entries appear

Cause: RxDB local-first sync may have conflicts.

Solution:

1. Check your network connection status
2. Wait for the sync indicator to show "Synced"
3. Refresh the page after reconnecting to the network
4. If duplicates appear, resolve by keeping the most recent version

Getting Help

If you cannot resolve your issue with the steps above:

1. Check the FAQ for additional answers
2. Note the specific error message, if any
3. Gather information for support:
   • What action you were performing
   • Steps to reproduce the issue
   • Screenshots of the problem
   • Browser and version (Chrome 120, Firefox 121, etc.)
   • Any console errors (F12 > Console tab)
4. Contact your FlowState administrator or support team