Troubleshooting

This guide covers common issues users encounter when using the Todo App and provides solutions.

Common Issues

Issue: "Authentication Required" Message

Symptoms:

• Cannot access todo list
• Prompted to sign in repeatedly
• "Authentication Required" appears on all pages

Cause: You are not signed in, or your session has expired.

Solution:

1. Sign in to FlowState:

   Click the "Sign In" button displayed on the page
   

2. Complete authentication using your email or phone number

3. Check browser settings - ensure cookies are enabled:

   • Authentication tokens are stored in cookies/localStorage
   • Private/incognito mode may prevent persistent login

4. Clear browser cache if sign-in keeps failing:

   Settings > Privacy > Clear browsing data > Cookies and site data
   

Issue: Todo List Not Loading

Symptoms:

• Empty todo list when you have todos
• Loading spinner that never completes
• "No todos found" message unexpectedly

Cause: Database connection issues or sync problems.

Solution:

1. Refresh the page:

   • Press Ctrl+R (Windows/Linux) or Cmd+R (Mac)

2. Check your network connection:

   • The app works offline, but initial sync requires connectivity

3. Verify RxDB database in browser DevTools:

   • Open DevTools (F12 or right-click > Inspect)
   • Go to Application > IndexedDB
   • Look for the todos collection

4. Clear IndexedDB and re-sync:

   Application > IndexedDB > Delete database > Refresh page
   

   Note: This will require data to sync again from the server.

Issue: Cannot Create New Todo

Symptoms:

• Save button doesn't work
• Form submission fails
• Todo not appearing in list after save

Cause: Validation errors, authentication issues, or database write failure.

Solution:

1. Check required fields:

   • Title is required
   • Ensure the title is not empty

2. Verify authentication:

   • Ensure you're signed in
   • Check the header for your email/phone

3. Check browser console for errors:

   Open DevTools > Console tab > Look for red error messages
   

4. Try refreshing and re-creating:

   • Refresh the page
   • Navigate to New Todo again
   • Re-enter the information

Issue: Todo Not Marking as Complete

Symptoms:

• Clicking complete doesn't change status
• Status reverts after toggling
• Completion state not persisting

Cause: Database update failing or optimistic update rollback.

Solution:

1. Wait for sync to complete:

   • Give the app a moment to persist the change
   • Check if the status updates after a few seconds

2. Refresh and try again:

   • Refresh the page
   • Navigate to the todo detail
   • Toggle completion again

3. Check for network issues:

   • If offline, changes may queue until online
   • Verify network connectivity

4. Verify in IndexedDB:

   • Open DevTools > Application > IndexedDB
   • Find your todo record
   • Check the completed field value

Issue: Due Dates Not Displaying Correctly

Symptoms:

• Due dates show wrong date
• Date format looks incorrect
• Timezone issues with due dates

Cause: Date formatting or timezone handling issues.

Solution:

1. Check your system timezone:

   • Dates are stored in ISO format (UTC)
   • Display converts to your local timezone

2. Verify the date you entered:

   • When creating a todo, ensure you selected the correct date
   • The date picker should show your local date

3. Clear and re-enter the due date:

   • Edit the todo
   • Clear the due date field
   • Re-select the desired date

Issue: App Displays Incorrectly or Unstyled

Symptoms:

• Missing styles or broken layout
• Buttons or navigation not visible
• White/blank page with text only

Cause: CSS not loading or browser compatibility issues.

Solution:

1. Hard refresh the page:

   • Press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

2. Clear browser cache:

   Settings > Privacy > Clear browsing data > Cached images and files
   

3. Try a different browser:

   • Use a modern browser (Chrome, Firefox, Safari, Edge)
   • Ensure browser is up to date

4. Disable browser extensions:

   • Ad blockers or privacy extensions may interfere
   • Try incognito/private mode without extensions

Issue: Sidebar Navigation Not Working

Symptoms:

• Clicking sidebar links does nothing
• Navigation stays on same page
• URL doesn't change

Cause: Router configuration or JavaScript error.

Solution:

1. Check for JavaScript errors:

   • Open DevTools > Console
   • Look for red error messages

2. Refresh the application:

   • Hard refresh with Ctrl+Shift+R or Cmd+Shift+R

3. Use direct URL navigation:

   • Type the URL directly in the address bar:
     • /todo/list for all todos
     • /todo/new for new todo

4. Clear all site data and reload:

   • DevTools > Application > Clear site data

Issue: App Won't Start in Standalone Mode (Development)

Symptoms:

• yarn dev fails to start
• Port already in use
• Module not found errors

Cause: Port conflict, missing dependencies, or configuration issues.

Solution:

1. Check port availability (default: 3211):

   # Check if port is in use
   lsof -i :3211
   
   # Kill the process if needed
   kill -9 <PID>
   

2. Reinstall dependencies:

   # From monorepo root
   yarn install
   

3. Build dependencies first:

   yarn nx build @epicdm/flowstate-app-framework
   

4. Check for TypeScript errors:

   yarn typecheck
   

Debugging Tips

Check Authentication State

Verify your authentication status:

1. Look at the header - your email/phone should be displayed
2. If you see "Sign In" prompt on pages, you're not authenticated
3. Check localStorage for auth tokens (DevTools > Application > Local Storage)

Inspect Database State

View the local RxDB database:

1. Open DevTools (F12)
2. Go to Application > IndexedDB
3. Expand the FlowState database
4. Look for the todos collection
5. Verify your todos exist and have correct data

View Network Requests

If sync issues occur:

1. Open DevTools > Network tab
2. Filter by Fetch/XHR
3. Look for failed requests (red status)
4. Check request/response details for errors

Check Console Logs

The app logs useful debugging information:

1. Open DevTools > Console
2. Look for [Todo] prefixed messages
3. Error messages appear in red
4. Warning messages appear in yellow

Browser Storage

The app uses browser storage for:

Getting Help

If you can't resolve your issue:

1. Review the Features & Capabilities documentation
2. Check the FAQ for common questions
3. Search existing issues in the monorepo
4. Contact support with:
   • Description of the issue
   • Steps to reproduce
   • Browser and version
   • Screenshots if applicable
   • Console error messages