GeoLog V2 Test iCloud

Troubleshooting Guide

This guide helps resolve common iCloud sync issues in GeoLog.

Table of Contents

Settings Not Syncing Between Devices

Symptom: You change Distance Unit (or other settings) on one device, but it doesn’t update on other devices.

Cause: The ModelContainer was created with iCloud sync disabled, so there’s no CloudKit connection to sync settings.

Quick Fix:

  1. On the device with incorrect settings, go to Settings → Data & Sync
  2. Toggle “Enable iCloud Sync” OFF
  3. Toggle “Enable iCloud Sync” ON
  4. Fully quit the app (swipe up from task switcher and remove it)
  5. Relaunch the app
  6. Settings should now sync from your other device within 30 seconds

Why this works: Toggling sync off/on updates the device’s local configuration and forces the ModelContainer to recreate with CloudKit enabled on next launch.

Settings UI Not Refreshing (While Settings Screen is Open)

Symptom: Settings screen is open on Device A when you change a setting on Device B. The change syncs in the background, but Device A’s Settings screen doesn’t update until you navigate away and come back.

Cause: SwiftUI wasn’t detecting when CloudKit imported setting changes in the background. The ModelContext was caching the SettingsModel object, and fetch() was returning the same cached instance even after CloudKit updated the persistent store.

Fixed in: Version with manual “Sync Settings” button

Solution – Use Manual Sync Button:

  1. When you notice settings are out of sync on a device:
  • Go to Settings → Data & Sync
  • Tap the “Sync Settings” button
  • The button will show a spinner while syncing
  • After sync completes, it shows “Last Synced: X ago”

How it works:

  • The manual sync button calls modelContext.rollback() to invalidate the cache
  • Forces a fresh fetch from the persistent store (which has CloudKit changes)
  • Increments a version counter to trigger SwiftUI refresh
  • All settings bindings re-evaluate and display updated values

Why automatic sync sometimes fails:

  • CloudKit notifications can be delayed due to network conditions
  • iOS may throttle background notifications when app is in foreground
  • The notification arrives but cached objects don’t get invalidated automatically
  • Manual sync button provides immediate control when you notice the issue

Best practice:

  • If you’re changing settings on one device while viewing Settings on another
  • Tap “Sync Settings” on the viewing device to pull latest changes immediately
  • The “Last Synced: X ago” timestamp confirms when settings were last refreshed

Locations/Photos Not Syncing

Symptom: You add a location on one device, but it never appears on other devices.

Root Cause: The app created the ModelContainer with CloudKit disabled, usually because:

  • iCloud Sync was never enabled
  • The app was reinstalled and UserDefaults was reset
  • You’re not signed into iCloud

Solution:

Step 1: Verify iCloud Account

  1. Open iOS Settings → [Your Name] → iCloud
  2. Verify you’re signed in with the same Apple ID on all devices
  3. Verify iCloud Drive is enabled

Step 2: Enable Sync on Primary Device

  1. On your primary device (the one with the most recent data):
  • Go to GeoLog Settings → Data & Sync
  • Toggle “Enable iCloud Sync” ON
  • Tap OK when prompted to restart
  • Fully quit the app (swipe from task switcher)
  • Relaunch the app
  1. Wait 2-3 minutes for initial upload to complete

Step 3: Enable Sync on Other Devices

  1. On each additional device:
  • Go to GeoLog Settings → Data & Sync
  • Toggle “Enable iCloud Sync” ON
  • Tap OK when prompted to restart
  • Fully quit the app
  • Relaunch the app
  1. Wait 1-2 minutes for data to sync down from iCloud

Step 4: Verify Sync is Working

  1. On any device, create a new location or take a photo
  2. On another device, check if it appears within 30 seconds
  3. If it appears, sync is working correctly

Full-Size Images Not Uploading/Downloading

Symptom: Full-size images show as “In iCloud” but won’t upload or download.

Upload Issues

Automatic Upload:

  • New photos (taken after enabling full-size sync) upload automatically when:
  • “Store full-size images in iCloud” is enabled
  • You’re on WiFi (if “WiFi Only Upload” is ON)
  • Upload happens immediately after capturing the photo
  • Existing photos (taken before enabling full-size sync) require manual sync:
  • Go to Settings → Data & Sync
  • Tap the blue Sync button next to “In iCloud: X of Y”
  • Or toggle full-size sync OFF then back ON

Check WiFi Connection:

  • Full-size uploads require WiFi by default
  • Go to Settings → Data & Sync
  • Verify “WiFi Only Upload” is ON
  • Connect to WiFi and try again
  • If you want to upload on cellular, turn “WiFi Only Upload” OFF

Manual Upload for Existing Photos:

  1. Go to Settings → Data & Sync
  2. Scroll to Full-Size Images section
  3. Check the count: “X photos pending upload”
  4. Tap the blue Sync button to start upload
  5. If stuck, try restarting the upload:
  • Tap Sync Now in the Sync Status section
  • Or disable and re-enable iCloud sync (requires app restart)

Upload/Download Stalled (Phone Went to Sleep)

Symptom: Upload shows “In iCloud: 218 of 344” and won’t continue. Upload started but stopped mid-process.

Cause: When your iPhone screen locks or goes to sleep, iOS suspends most app activity, including CloudKit uploads/downloads. The upload stalls at whatever count it reached before sleep.

Quick Fix – Use the Resume Button:

  1. Go to Settings → Data & Sync
  2. Look for the blue “Sync” button next to “In iCloud: 218 of 344”
  3. Tap the Sync button to resume upload from where it stopped
  4. Upload will continue from photo 219

The Sync Button:

  • Appears when there are pending uploads/downloads that aren’t currently running
  • Only shows when upload has stalled (not during active upload)
  • Blue rounded square button with sync icon and “Sync” label
  • Tapping it resumes upload from where it left off

Automatic Prevention:

  • The app now automatically prevents screen auto-lock during uploads/downloads
  • Your screen will stay on while sync is in progress
  • Screen auto-lock re-enables automatically when upload completes
  • You can still manually lock your phone (power button), which will pause the upload

Best Practices:

  1. Start large uploads when you can keep the app in foreground
  2. Plug in to charger during large syncs
  3. If you need to leave, just let it run – screen will stay on automatically
  4. If upload stalls, use the blue Sync button to resume anytime

Download Issues

Images download on-demand by default:

  • When you open a photo in full-screen, it auto-downloads from iCloud
  • If download fails, you’ll see a download button
  • Tap the button to manually download

Download all images for offline access:

  1. Go to Settings → Data & Sync
  2. Scroll to Full-Size Images section
  3. Tap “Download All iCloud Photos”
  4. Wait for download to complete (shown with progress bar)

Storage Quota Exceeded:

  • iCloud free tier is 1GB
  • If you exceed your quota, uploads will fail
  • Check Settings → Storage Usage to see current usage
  • Disable full-size sync or upgrade iCloud storage plan

Missing Full-Size Images (Validation)

Symptom: You can see thumbnails of photos, but when you open them in full-screen view, they show “No image available” or fail to download from iCloud.

What Happened: The app database shows photos as fullSizeInCloud = true, but the actual CloudKit asset is missing. This can happen if:

  • Images were deleted from iCloud manually (via CloudKit Dashboard)
  • A device deleted images while offline and sync conflicts occurred
  • CloudKit storage quota was exceeded during upload
  • The “Store full-size images in iCloud” toggle was turned OFF (in older app versions)

Automatic Validation & Repair

New Feature: GeoLog now automatically validates full-size images during sync.

How to Use:

  1. Go to Settings → Data & Sync
  2. Scroll to Sync Status section
  3. Tap Sync Now
  4. A progress overlay will show:
  • “Syncing with iCloud…” (2 seconds)
  • “Validating X of Y” with progress bar (if full-size enabled)
  1. After completion, you’ll see validation results:
  • ✓ “All X locations validated” – All location data synced
  • ✓ “All Y full-size images validated” – All images exist in iCloud
  • ⚠️ “Found N missing image(s) in iCloud (fixed: N)” – Issues found and repaired

What Gets Fixed:

  • Photos marked as fullSizeInCloud = true but missing from CloudKit are automatically updated
  • Their flags are corrected to fullSizeInCloud = false
  • These photos will be re-uploaded on next sync (if they exist locally)
  • You’ll know exactly how many images need re-uploading

When to Run Validation:

  • After enabling iCloud sync on a new device
  • If photos show as “in cloud” but won’t download
  • After recovering from iCloud storage quota issues
  • Periodically (monthly) to ensure data integrity

Manual Recovery for Missing Images

If validation shows missing images and they exist locally on another device:

  1. Find the device with local copies:
  • Check which device has the missing photos locally
  • Go to Settings → Data & Sync → Storage Usage
  • Look for devices with higher local storage usage
  1. Re-upload from that device:
  • On the device with local copies, go to Settings → Data & Sync
  • Ensure “Store full-size images in iCloud” is ON
  • Tap the blue Sync button next to “In iCloud: X of Y”
  • Wait for upload to complete
  1. Verify on other devices:
  • On other devices, tap Sync Now
  • Photos should now download successfully

Preventing Future Issues

Important Change: Toggling “Store full-size images in iCloud” OFF no longer deletes images from iCloud. Images remain safely stored and available for download.

To Actually Remove Images from iCloud:

  1. Go to Settings → Data & Sync
  2. Scroll to Danger Zone (red section at bottom)
  3. Tap “Remove All Full-Size Images from iCloud”
  4. Confirm the destructive action
  5. Images will be permanently deleted from iCloud (local copies remain)

Understanding the Options:

  • Toggle OFF: Stops uploading new images, keeps existing images in iCloud
  • “Remove All Full-Size Images”: Permanently deletes all images from iCloud
  • “Delete All GeoLog Data”: Deletes everything (locations, photos, settings) from both device and iCloud

Clean Slate Procedure

When to use: If sync is completely broken and you want to start fresh.

⚠️ WARNING: This deletes all iCloud data. Your local data remains safe, but you’ll need to re-sync everything.

Steps:

  1. Choose Your Primary Device
  • Pick the device with the most complete/recent data
  • This will become the source of truth for all devices
  1. Delete iCloud Data
  • On the primary device: Settings → Data & Sync
  • Scroll to Danger Zone
  • Tap “Delete All iCloud Data”
  • Confirm deletion
  • Wait for deletion to complete (progress bar will show)
  1. Disable Sync on All Devices
  • On ALL devices (including primary):
    • Go to Settings → Data & Sync
    • Toggle “Enable iCloud Sync” OFF
    • Fully quit the app
  1. Wait 60 Seconds
  • Allows CloudKit deletions to propagate
  1. Re-enable Sync on Primary Device
  • On primary device only:
    • Launch the app
    • Go to Settings → Data & Sync
    • Toggle “Enable iCloud Sync” ON
    • Fully quit and relaunch the app
  • Wait 2-3 minutes for initial sync to complete
  1. Enable Sync on Other Devices
  • On each additional device:
    • Launch the app
    • Go to Settings → Data & Sync
    • Toggle “Enable iCloud Sync” ON
    • Fully quit and relaunch the app
  • Wait 1-2 minutes for sync to download data
  1. Verify Sync Works
  • Create a test location on one device
  • Verify it appears on other devices within 30 seconds

Verifying Sync Status

Check if Sync is Enabled

  1. Go to Settings → Data & Sync
  2. Look at the Sync Control section:
  • If toggle is ON and shows blue “iCloud.fill” icon → Sync is enabled
  • If toggle is OFF and shows gray “iCloud.slash” icon → Sync is disabled

Check if Restart is Required

  1. Go to Settings → Data & Sync
  2. Look for orange warning box:
  • “Restart Required” → You changed sync settings, app needs restart
  • No warning → Sync settings match current state
  1. If restart required:
  • Fully quit the app (swipe from task switcher)
  • Relaunch the app
  • Check if warning is gone

Check Sync Status (Advanced – Requires Xcode Console)

For developers only:

  1. Connect device to Mac with Xcode
  2. Open Console in Xcode while app is running
  3. Look for this log line during app launch:
   📦 Creating ModelContainer with iCloud sync: ENABLED
  • If you see ENABLED → CloudKit is active, sync will work
  • If you see DISABLED → CloudKit is off, sync won’t work
  1. If DISABLED when it should be ENABLED:
  • Toggle sync OFF → ON in Settings
  • Fully quit and relaunch
  • Check logs again

Common Issues

“Not signed into iCloud”

Symptom: Orange warning in Settings showing “Not signed into iCloud”

Solution:

  1. Open iOS Settings (not GeoLog settings)
  2. Tap your name at the top
  3. Sign in with your Apple ID
  4. Enable iCloud Drive
  5. Return to GeoLog and try again

Settings Sync Stopped Working

Symptom: Settings were syncing, now they’re not

Quick Fix:

  1. On the device with wrong settings:
  • Toggle sync OFF
  • Toggle sync ON
  • Fully quit and relaunch
  • Settings should sync within 30 seconds

If that doesn’t work:

Full-Size Toggle Doesn’t Match Between Devices

Symptom: iPhone shows “Store full-size images” is ON, iPad shows OFF

Cause: Same as settings not syncing – CloudKit is disabled

Solution:

  1. On the device with incorrect toggle state:
  • Go to Settings → Data & Sync
  • Toggle “Enable iCloud Sync” OFF then ON
  • Fully quit and relaunch
  • Toggle should now match other devices

App Crashes After Enabling Sync

Symptom: App crashes immediately after enabling iCloud Sync and restarting

Cause: This was a bug with unique constraints (fixed in version X.X)

Solution:

  1. Update to the latest version of GeoLog
  2. If already on latest version:
  • Delete the app completely
  • Reinstall from Xcode/TestFlight/App Store
  • Do NOT restore from iCloud backup during install
  • Follow Clean Slate Procedure to sync data

Upload Stalled Mid-Process

Symptom: Upload stopped at “In iCloud: 218 of 344” and won’t continue

Cause: Phone went to sleep or app was backgrounded

Quick Fix:

  1. Go to Settings → Data & Sync
  2. Tap the blue Sync button next to “In iCloud: 218 of 344”
  3. Upload resumes from where it stopped

Details: See Upload/Download Stalled for full explanation

“Storage Quota Exceeded”

Symptom: Error message about storage quota when uploading full-size images

Cause: You’ve exceeded your iCloud storage limit (1GB free tier)

Solution Option 1: Remove Full-Size Images from iCloud

  1. Go to Settings → Data & Sync
  2. Toggle “Store full-size images in iCloud” OFF (stops new uploads, keeps existing images)
  3. Optional: To free up space, go to Danger Zone section
  4. Tap “Remove All Full-Size Images from iCloud”
  5. Confirm deletion
  6. Only thumbnails will remain in iCloud (uses ~20KB per photo instead of ~2-4MB)

Solution Option 2: Upgrade iCloud Storage

  1. Open iOS Settings → [Your Name] → iCloud → Manage Storage
  2. Tap “Change Storage Plan”
  3. Select a larger plan (50GB, 200GB, 2TB)
  4. Return to GeoLog
  5. Tap Sync Now to resume uploading remaining images

Storage Estimates:

  • 1,000 photos with thumbnails only: ~24 MB
  • 1,000 photos with full-size: ~117 MB (within 1GB free tier)
  • 5,000 photos with full-size: ~585 MB (within 1GB free tier)
  • 8,500 photos with full-size: ~993 MB (near 1GB limit)

Important: Toggling OFF no longer deletes images automatically. Use the “Remove All Full-Size Images” button in Danger Zone to actually free up iCloud storage.

Best Practices

Multi-Device Setup

  1. Always enable sync on your primary device first
  • The device with the most complete/recent data
  • Let it fully sync to iCloud (2-3 minutes)
  • Then enable on other devices
  1. Wait between enabling devices
  • Don’t enable sync on all devices simultaneously
  • Enable on primary → wait → enable on secondary → wait → etc.
  1. Restart is ALWAYS required
  • When toggling sync ON or OFF, you MUST restart the app
  • Use the task switcher to fully quit (swipe up)
  • Not just minimizing – actually quit and relaunch

Full-Size Image Sync

  1. Only enable if you have good WiFi
  • Full-size images are 2-4MB each
  • Uploading hundreds of photos takes time
  • Keep WiFi-only upload enabled unless you have unlimited data
  1. Monitor your storage usage
  • Check Settings → Storage Usage regularly
  • Toggle OFF full-size sync before hitting 80% of quota
  • Use “Remove All Full-Size Images” in Danger Zone to free up space
  • Most users don’t need full-size sync – thumbnails are sufficient
  1. On-demand is the default
  • The Full-size image is always on the device on which it originated from. Other devices relieve full-size image on-demand.
  • Full-size images download automatically when you view them
  • No need to manually download unless you want offline access
  • Use “Download All” button only before going offline (airplane, remote areas)
  1. Run validation periodically
  • Tap Sync Now monthly to validate full-size images
  • Checks that all images marked as “in cloud” actually exist
  • Automatically repairs inconsistent photo states
  • Look for ✓ “All X full-size images validated” message

Sync Troubleshooting Checklist

Before asking for help, try these steps:

  • [ ] Verified signed into iCloud on all devices (same Apple ID)
  • [ ] Verified iCloud Drive is enabled in iOS Settings
  • [ ] Toggled sync OFF → ON on affected device
  • [ ] Fully quit and relaunched the app (not just minimized)
  • [ ] Waited 60 seconds for sync to complete
  • [ ] Checked for “Restart Required” warning in Settings
  • [ ] Verified device has internet connection (WiFi or cellular)
  • [ ] Checked iCloud storage quota (Settings → Storage Usage)
  • [ ] Ran validation by tapping Sync Now (checks for missing images)

If all above steps fail, try the Clean Slate Procedure.

Technical Background (For Developers)

Why Restart is Required

GeoLog uses SwiftData’s CloudKit integration, which requires the ModelContainer to be configured at creation time with either:

  • ModelConfiguration(cloudKitDatabase: .automatic) – sync enabled
  • ModelConfiguration(cloudKitDatabase: .none) – sync disabled

The container cannot be reconfigured after creation. When you toggle sync on/off, the app stores the preference in two places:

  1. SettingsModel.iCloudSyncEnabled (synced via CloudKit to other devices)
  2. UserDefaults.standard.bool(forKey: "iCloudSyncEnabled") (device-local)

On app launch, it reads from UserDefaults to create the container with the correct configuration. This is why restarting is mandatory.

The Chicken-and-Egg Problem

Settings sync requires CloudKit, but CloudKit configuration requires knowing if sync is enabled before creating the container. This creates a chicken-and-egg problem:

  1. User enables sync on iPhone → stores in SettingsModel + UserDefaults
  2. SettingsModel syncs to iPad via CloudKit
  3. iPad’s refreshSettings() updates its SettingsModel
  4. But iPad’s UserDefaults is still false (device-local, not synced)
  5. iPad creates container with CloudKit DISABLED
  6. Without CloudKit, settings can’t sync

The Fix: When refreshSettings() detects CloudKit imported a change to iCloudSyncEnabled, it now updates the device-local UserDefaults immediately. The next app restart will create the container with the correct CloudKit configuration.

Duplicate SettingsModel Records

Earlier versions allowed multiple SettingsModel records to exist, causing each device to potentially read a different record. This has been fixed by:

  1. All devices fetch the canonical record with settingsKey == "primary-settings"
  2. Sort by lastModifiedDate descending so all devices agree on which record is canonical
  3. Cleanup duplicate records automatically on app launch

Getting Help

If you’ve tried all troubleshooting steps and sync still doesn’t work:

  1. Collect diagnostic information:
  • iOS version on all devices
  • GeoLog version number
  • Number of locations and photos
  • iCloud storage quota and current usage
  • Screenshots of Settings → Data & Sync screen
  1. If possible, connect device to Xcode and capture console logs during:
  • App launch (look for “Creating ModelContainer with iCloud sync: ENABLED/DISABLED”)
  • Toggling sync on/off
  • Creating a test location
  1. Report the issue with all diagnostic information

Recent Updates

January 18, 2026:

  • Added automatic full-size image validation during sync
  • Toggling “Store full-size images in iCloud” OFF no longer deletes images
  • New “Remove All Full-Size Images” button in Danger Zone for intentional deletion
  • Sync Now displays progress and validation results
  • Validation automatically repairs photos marked as in-cloud but missing from CloudKit
  • Added manual “Sync Settings” button in Data & Sync section
  • Provides immediate control when settings don’t auto-refresh
  • Shows spinner during sync and “Last Synced: X ago” timestamp
  • Invalidates ModelContext cache and forces fresh fetch from CloudKit
  • Fixes issue where Settings screen wouldn’t update when open during background sync
  • Moved photo export to Gallery view
  • Removed individual “Export to Photo Library” and “Saved to Photo Library” buttons from Location Detail
  • Added “Export Gallery” button in Gallery view to export all photos at once
  • Shows progress overlay during bulk export

Last Updated: January 26, 2026