- Introduction
- What Are Conflicts?
- Why Conflicts Happen
- How Automatic Resolution Works
- How to Manually Resolve Conflicts
- Understanding the Sync Status Indicator
- Tips for Avoiding Conflicts
- Troubleshooting Common Issues
- Frequently Asked Questions
The Grocery List app works seamlessly whether you're online or offline. When you're offline, all your changes are saved locally and automatically synced when you reconnect. This guide explains how the app handles situations where different users make conflicting changes to the same items while offline.
Key Features:
- Your changes are never lost - all edits are queued and synced when online
- Most conflicts are resolved automatically without user intervention
- Clear indicators show when items are queued for sync
- Manual resolution available when automatic resolution isn't possible
A conflict occurs when two or more users make different changes to the same grocery item while at least one user is offline. When everyone comes back online, the app needs to decide which changes to keep.
Two users edit the same field of an item differently.
Example:
- User A (offline): Changes quantity from 1 to 2
- User B (offline): Changes quantity from 1 to 3
- Conflict: Which quantity should win?
One user edits an item while another deletes it.
Example:
- User A (offline): Marks "Milk" as gotten
- User B (offline): Deletes "Milk"
- Conflict: Should the item be kept or deleted?
Different fields of the same item are edited by different users.
Example:
- User A (offline): Changes quantity to 2
- User B (offline): Changes notes to "Organic"
- No Conflict: These changes don't conflict and are merged automatically
Conflicts are a natural part of collaborative offline-first apps. Here are common scenarios:
User A is shopping with spotty WiFi
├─ Marks items as gotten while offline
├─ User B at home removes some items
└─ When User A reconnects → potential conflicts
Family members shop independently
├─ Mom buys milk (marks as gotten)
├─ Dad also buys milk (different quantity)
└─ Both sync later → conflict on the milk item
Two users editing the same item at the same time
├─ User A: Changes "Apples" to "Green Apples"
├─ User B: Changes "Apples" to "Red Apples"
└─ Sync happens → name conflict
Users in different time zones
├─ User A edits at 9 AM local time
├─ User B edits at "same time" but different zone
└─ Timestamps might be close → conflict resolution needed
The app uses intelligent strategies to resolve most conflicts automatically without bothering you. Here's how:
The most recent change wins based on timestamp.
How it works:
Change A: Made at 10:00 AM
Change B: Made at 10:05 AM
Result: Change B wins (more recent)
Best for:
- Simple updates that don't have semantic meaning
- When the latest information is usually correct
Example:
User A (10:00 AM): Updates quantity to 2
User B (10:05 AM): Updates quantity to 3
Resolution: Quantity = 3 (User B's newer change wins)
If one version marks an item as "gotten" and the other doesn't, the "gotten" version wins.
Why this matters: Prevents the frustrating scenario where you mark an item as gotten, but a sync reverts it back to "not gotten."
Example:
User A: Marks "Milk" as gotten ✓
User B: Edits milk quantity to 2 (not gotten)
Resolution: Milk is gotten ✓ with quantity 2 (merged)
When different fields are modified, combine all changes intelligently.
How it works:
Local: { quantity: 2, notes: "Organic" }
Remote: { quantity: 2, gotten: true }
Merged: { quantity: 2, notes: "Organic", gotten: true }
Special field handling:
- gotten: Always prefer
true(someone got the item) - quantity: Use the higher value (someone needed more)
- notes: Concatenate with " | " separator
- name: Keep most recent (requires manual resolution if critical)
- category: Keep most recent
Example:
User A: Adds note "Low fat" + quantity 2
User B: Marks as gotten
Merged:
- quantity: 2 (from A)
- notes: "Low fat" (from A)
- gotten: true (from B)
When both users increase quantity, use the higher value.
Example:
Original: quantity = 1
User A: Increases to 3
User B: Increases to 5
Resolution: quantity = 5 (higher value, more needed)
Automatic resolution is NOT used when:
- Critical fields conflict (name, category)
- Timestamps are too close (within 5 minutes)
- Both users deleted the same item
- Semantic conflicts that need human judgment
In these cases, the app will notify you and provide a manual resolution interface.
When automatic resolution isn't possible, you'll be prompted to manually resolve the conflict.
When a conflict requires manual resolution, you'll see:
┌─────────────────────────────────────┐
│ ⚠️ Conflict Detected │
│ │
│ 1 item requires your attention │
│ │
│ [View Conflict] │
└─────────────────────────────────────┘
Click "View Conflict" to see the conflict details:
┌─────────────────────────────────────┐
│ Conflict: Milk │
│ Type: Field conflict │
│ │
│ Your Version (Local): │
│ ├─ Name: Whole Milk │
│ ├─ Quantity: 2 │
│ └─ Notes: Organic │
│ │
│ Other Version (Remote): │
│ ├─ Name: Skim Milk │
│ ├─ Quantity: 3 │
│ └─ Notes: Store brand │
│ │
│ Fields in conflict: │
│ ├─ ⚠️ Name (critical) │
│ ├─ ⚠️ Quantity │
│ └─ ⚠️ Notes │
└─────────────────────────────────────┘
You have four options:
Option 1: Keep Your Version
[Keep Mine] → Uses all local changes
Result: Whole Milk, quantity 2, notes "Organic"
Option 2: Keep Other Version
[Keep Theirs] → Uses all remote changes
Result: Skim Milk, quantity 3, notes "Store brand"
Option 3: Merge Fields
[Smart Merge] → Intelligently combines both
Result: Newer name + higher quantity + merged notes
Whole Milk, quantity 3, notes "Organic | Store brand"
Option 4: Custom Resolution
[Edit Manually] → Create your own version
You type: Regular Milk, quantity 4, notes "Either brand"
After choosing, confirm your selection:
┌─────────────────────────────────────┐
│ Resolution Preview │
│ │
│ Final version: │
│ ├─ Name: Whole Milk │
│ ├─ Quantity: 3 │
│ └─ Notes: Organic | Store brand │
│ │
│ [Cancel] [Apply Resolution] │
└─────────────────────────────────────┘
After resolving, the item syncs with your chosen resolution:
✓ Conflict resolved successfully
All changes have been synced
The app provides a sync status indicator to show the current state of your offline queue and conflicts.
● Online
- Connected to the server
- All changes synced
- No queued mutations
- Everything up to date
◐ Syncing...
- Connected to the server
- Actively syncing changes
- Queue is being processed
- Wait for completion
● Offline
- No internet connection
- Changes are queued locally
- Will sync when reconnected
- You can still edit items
⚠ Conflicts (2)
- Connected to server
- Some conflicts require resolution
- Click to view and resolve
- Other changes may be syncing
Click the status indicator to expand details:
┌─────────────────────────────────────┐
│ Sync Status │
│ │
│ Connection: [● Online] │
│ Quality: [● Good] │
│ Status: [◐ Syncing...] │
│ Queued: 5 items │
│ Last sync: 2m ago │
│ │
│ [Retry Sync] │
│ │
│ ℹ️ Some changes are waiting to │
│ sync. Click "Retry Sync" if │
│ needed. │
└─────────────────────────────────────┘
● Good: Last synced within 5 minutes
- Normal operation
- Quick sync times
- Reliable connection
◐ Poor: Last synced over 5 minutes ago
- Slow or intermittent connection
- Sync delays
- Consider finding better signal
While the app handles conflicts automatically, here are best practices to minimize them:
Before editing, make sure you're synced:
✓ Check status indicator is green
✓ Wait for "All changes synced" message
✓ Then start editing
If multiple people are shopping:
✓ Agree on who edits what items
✓ Use notes to indicate "in progress"
✓ Avoid editing the same items simultaneously
Instead of:
❌ Making 20 changes offline
❌ Then syncing all at once
Do this:
✓ Make 2-3 changes
✓ Sync when possible
✓ Repeat
Add notes to indicate status:
✓ "Checking store" - You're looking for it
✓ "In cart" - You have it
✓ "Not available" - Couldn't find it
Instead of:
❌ Deleting items after getting them
Do this:
✓ Mark items as "gotten" ✓
✓ Let the app clean up later
Keep auto-sync enabled:
Settings → Sync → Auto-sync: [ON]
Check connection quality:
Poor connection → Wait before editing
Good connection → Edit freely
When using "Delete All Gotten":
✓ Sync first
✓ Make sure others synced
✓ Then bulk delete
Symptoms:
- Items show as queued
- Sync status stuck
- Changes don't appear on other devices
Solutions:
-
Check Internet Connection
Settings → WiFi/Mobile Data → Verify connected -
Check Status Indicator
Red dot → You're offline (expected) Yellow dot → Syncing in progress (wait) Green dot → Should be synced (retry if not) -
Force Retry
Click status indicator → [Retry Sync] -
Clear Queue and Re-add
If stuck: - Export your list (backup) - Clear offline queue (Settings → Advanced) - Refresh page - Re-add items if needed
Symptoms:
- Frequent conflict notifications
- Constant manual resolution required
- Frustrating user experience
Solutions:
-
Coordinate with Team
Talk to other users about who edits what -
Establish Editing Rules
Example rules: - Person shopping has edit priority - Person at home views only - Wait for sync before bulk operations -
Use List Permissions
Share list with appropriate permissions: - Owner: Full control - Editor: Can edit items - Viewer: Read-only (no conflicts!) -
Check Timestamps
Settings → Advanced → "Fix Clock Skew" Ensures timestamps are accurate
Symptoms:
- Made changes while offline
- Changes disappeared after syncing
- Item reverted to old version
Solutions:
-
Check Conflict Log
Settings → Sync → Conflict History See if your change was overridden -
Verify Timestamps
Your device clock must be accurate Settings → Date & Time → Auto-set time [ON] -
Look for Merged Items
Your changes might be merged into another item Check notes field for concatenated text -
Contact List Owner
If changes consistently disappear: - Verify you have Editor permission (not Viewer) - Ask owner to check server logs
Symptoms:
- Syncing... message persists
- Queue not clearing
- Long wait times
Solutions:
-
Check Queue Size
Click status indicator → See "Queued: X items" Large queue = longer sync time -
Check Connection Quality
Poor connection → Slow sync Switch to WiFi if on mobile data -
Reduce Queue Size
Instead of queuing 50 items: - Sync in batches of 10 - Wait for each batch to complete -
Clear Failed Items
Settings → Sync → Failed Items → Clear Retry failed items individually
Symptoms:
- Conflict resolution applied
- Conflict reappears
- Can't dismiss conflict
Solutions:
-
Check Other Devices
Another device might be offline with conflicting changes Wait for all devices to sync -
Force Full Sync
Settings → Sync → [Force Full Sync] Downloads all server data Resolves stubborn conflicts -
Recreate Item
Last resort: - Delete conflicting item on all devices - Wait for sync - Create item fresh
Symptoms:
❌ Error: Max retries exceeded for mutation
Meaning: The app tried to sync a change 5 times and failed each time.
Solutions:
-
Check Error Details
Click status indicator → Failed Items → View Error -
Common Errors and Fixes:
-
"Item not found": Item was deleted on server
- Solution: Remove from queue, re-add if needed
-
"Permission denied": Your permission changed
- Solution: Ask owner to restore Editor permission
-
"Invalid data": Corrupted queue entry
- Solution: Clear queue entry, re-add item
-
"Network timeout": Server unreachable
- Solution: Check server status, retry later
-
-
Clear Failed Mutation
Settings → Sync → Failed Items Find the item → [Remove from Queue] -
Re-add Manually
After clearing failed mutation: - Note the item details - Remove from queue - Add item again manually
A: No! All offline changes are persisted to your browser's local storage. Even if you:
- Close the browser tab
- Restart your device
- Turn off your computer
Your changes will be there when you return and will sync when you reconnect.
A: Indefinitely. Changes stay in the queue until:
- Successfully synced to the server, OR
- You manually clear them, OR
- You clear browser data/cookies
Best practice: Sync within 7 days to avoid clock skew issues.
A: Yes! Click the sync status indicator to see:
- Number of queued items
- Last sync time
- Current sync status
- Failed items (if any)
For detailed queue view:
Settings → Sync → Offline Queue → View Details
A: No conflict! Both deletions are idempotent:
- First deletion removes the item
- Second deletion finds it already deleted
- No error, no conflict
A: Not recommended, but if needed:
Settings → Sync → Offline Mode → [OFF]
Warning: With offline mode disabled:
- Cannot edit when offline
- Changes won't queue
- May see errors instead
A: The app uses intelligent retry with exponential backoff:
- First retry: Wait 1 second
- Second retry: Wait 2 seconds
- Third retry: Wait 4 seconds
- Fourth retry: Wait 8 seconds
- Fifth retry: Wait 16 seconds
- After 5 failures: Mark as failed, manual retry needed
This prevents overwhelming slow connections while ensuring eventual sync.
A: Wrong timestamps can cause conflict resolution issues. The app:
- Uses your device's system time for timestamps
- Warns if clock skew detected (>5 minutes difference from server)
- Suggests enabling automatic time sync
Fix:
Device Settings → Date & Time → Set Automatically [ON]
A: Not directly, but you can:
-
View Conflict History
Settings → Sync → Conflict Log -
See What Changed
Find the resolved conflict View "Before" and "After" snapshots -
Manually Revert
Edit the item back to desired state Will sync as a new change
A: Yes! When offline, you can:
- ✓ Add items
- ✓ Edit items
- ✓ Delete items
- ✓ Mark items as gotten
- ✓ Search and filter items
- ✓ View all lists
You CANNOT:
- ✗ Share lists (requires server)
- ✗ Add new members (requires server)
- ✗ See changes from others until you sync
A: There's no limit, but in practice:
- Typical: 0-2 conflicts per sync
- Common: 3-5 conflicts (family shopping separately)
- Rare: 10+ conflicts (indicates coordination issue)
If you consistently have 10+ conflicts, review your team's editing practices.
A: Yes! Every conflict resolution is logged with:
- Timestamp of conflict
- Timestamp of resolution
- User who resolved
- Strategy used (auto vs manual)
- Before/after snapshots
- Resolution outcome
View logs:
Settings → Sync → Conflict Log
A: Yes!
Settings → Sync → Conflict Log → [Export as JSON]
Useful for:
- Troubleshooting patterns
- Team coordination review
- Audit trail
The Grocery List app's offline conflict resolution system ensures that:
✓ Your changes are never lost - all edits are queued and persisted ✓ Most conflicts resolve automatically - intelligent strategies handle common cases ✓ Clear visibility - sync status always visible ✓ Manual control when needed - you decide on complex conflicts ✓ Reliable synchronization - automatic retry with exponential backoff
By following the best practices in this guide, you can minimize conflicts and enjoy seamless collaboration whether you're online or offline.
Quick Reference:
- 🟢 Green = All synced
- 🟡 Yellow = Syncing in progress
- 🔴 Red = Offline (changes queued)
⚠️ Orange = Conflicts need resolution
For technical details, see:
Need Help?
If you encounter issues not covered in this guide:
- Check the Troubleshooting section
- View conflict logs:
Settings → Sync → Conflict Log - Contact your list owner or system administrator
- Report bugs to the development team
Version: 1.0.0 Last Updated: October 2025