Troubleshooting

This guide addresses common issues you may encounter while using the Org App.

Common Issues

Issue: No Organizations or Workspaces Displayed

Symptoms:

• Organization list is empty
• Workspace list shows no items
• "No data available" messages appear

Cause: No organizations or workspaces have been created yet, or you lack permissions to view them.

Solution:

1. Click the Create Organization button on the Orgs page
2. Complete the organization creation form
3. Navigate to Workspaces and create your first workspace
4. If you expect to see existing data, verify your account permissions

Issue: Organization Not Selected After Creation

Symptoms:

• Created an organization but it's not active
• Other apps show "No organization selected"
• Data appears to be missing

Cause: Auto-selection only occurs when no organization was previously selected.

Solution:

1. Navigate to the Orgs page
2. Click on the organization you want to select
3. The selection will be persisted to local storage
4. Other FlowState apps will now use this organization context

Issue: Workspace Creation Fails

Symptoms:

• "Failed to create workspace" error
• Form validation errors
• Workspace doesn't appear after saving

Cause: Missing required fields, no organization selected, or validation errors.

Solution:

1. Ensure an organization is selected first
2. Verify all required fields are filled:
   • Workspace name (required)
   • Parent organization (required)
3. Check for duplicate workspace names within the organization
4. Refresh the page and try again if the issue persists

Issue: Attributes Not Seeding

Symptoms:

• "Seed Defaults" button doesn't work
• No attributes appear after seeding
• Seed operation completes but list is empty

Cause: Seeding may skip existing attributes or encounter database issues.

Solution:

1. Check if attributes already exist (seeding skips duplicates)
2. Try seeding from multiple presets using Seed from Presets
3. Verify your database permissions
4. Check the browser console for error messages (F12 > Console)
5. Manually create attributes if seeding continues to fail

Issue: Attribute Color Not Saving

Symptoms:

• Selected color reverts to default
• Color picker selection doesn't apply
• Attributes all show the same color

Cause: Form state issue or color value not properly captured.

Solution:

1. Click directly on a color in the palette to select it
2. Ensure the color indicator shows your selection before saving
3. Wait for the form to update before clicking Save
4. Try a different browser if the issue persists

Issue: OAuth Connection Fails (Sync)

Symptoms:

• OAuth popup doesn't appear or closes immediately
• "Failed to connect" error message
• Callback URL error

Cause: Pop-up blocked, OAuth flow interrupted, or provider configuration issues.

Solution:

1. Ensure pop-ups are allowed for the FlowState domain
2. Disable ad blockers temporarily during connection
3. Clear browser cookies and try again
4. Try a different browser (Chrome recommended)
5. Verify the sync provider credentials are configured correctly
6. Check if the external service (GitHub) is operational

Issue: GitHub Sync Not Working

Symptoms:

• Connected to GitHub but no data syncs
• Repositories don't appear
• Sync status shows errors

Cause: Insufficient permissions, rate limits, or repository access issues.

Solution:

1. Verify your GitHub OAuth token has required scopes:
   • repo - for private repositories
   • read:org - for organization data
2. Check if you've exceeded GitHub API rate limits (wait and retry)
3. Ensure you have access to the repositories you're trying to sync
4. Disconnect and reconnect to refresh the OAuth token
5. Check GitHub's status page for service issues

Issue: User List Not Loading

Symptoms:

• Users page shows loading spinner indefinitely
• User list is empty when users should exist
• "Failed to load users" error

Cause: Network issues, permissions, or database connectivity.

Solution:

1. Refresh the page
2. Verify you have permissions to view users
3. Check your network connection
4. Ensure an organization is selected
5. Check the browser console for specific errors

Issue: Selection Not Persisting

Symptoms:

• Organization/workspace resets after browser refresh
• Must re-select org/workspace each session
• Other apps don't see your selection

Cause: Local storage issues or browser privacy settings.

Solution:

1. Check that local storage is enabled in your browser
2. Verify you're not in private/incognito mode
3. Clear site data and re-select your organization
4. Ensure cookies are allowed for the FlowState domain
5. Try a different browser to isolate the issue

Issue: Attribute Deletion Fails

Symptoms:

• Delete button doesn't work
• "Cannot delete attribute" error
• Attribute remains in list after deletion

Cause: Attribute may be in use by other entities or protected.

Solution:

1. Check if the attribute is used by projects, tasks, or other entities
2. Remove attribute associations before attempting deletion
3. Consider archiving the attribute instead of deleting
4. Verify you have delete permissions
5. Check the browser console for specific error messages

Issue: App Won't Load or Shows Blank Screen

Symptoms:

• White screen after navigating to app
• Loading spinner never completes
• Console shows JavaScript errors

Cause: Browser compatibility, network issues, or corrupt local data.

Solution:

1. Try a hard refresh (Ctrl/Cmd + Shift + R)
2. Clear browser cache and cookies
3. Try a different browser (Chrome, Firefox, Safari, Edge)
4. Check your internet connection
5. Disable browser extensions temporarily
6. Check browser console for specific errors (F12 > Console)

Issue: Data Not Saving

Symptoms:

• Changes disappear after navigation
• Save actions have no effect
• Form submissions don't update data

Cause: Session expired, database sync issues, or validation errors.

Solution:

1. Check if you're still logged in
2. Look for validation error messages on the form
3. Refresh the page and try again
4. Check the browser console for error messages
5. Verify your network connection is stable

Performance Issues

Issue: App Running Slowly

Symptoms:

• Slow page loads
• Delayed response to clicks
• Lists take long to render

Cause: Large data sets, network latency, or browser resources.

Solution:

1. Close other browser tabs to free memory
2. Clear browser cache
3. Check your network speed
4. If you have many organizations/workspaces, use search or filtering
5. Ensure you're using a supported browser version

Getting Help

If you cannot resolve your issue using this guide:

1. Check the FAQ for additional answers
2. Review the Features documentation for proper usage
3. Contact support with the following information:
   • Description of the issue
   • Steps to reproduce the problem
   • Screenshots of any error messages
   • Browser name and version
   • Device type (desktop/mobile)
   • Any error messages from the browser console (F12 > Console)