Common Issues

Frequently encountered issues in TheCompanyApp and their solutions.

Installation & Setup

Issue: App Won't Install from TestFlight

Symptom: "Unable to Install" error when tapping Install in TestFlight.

Causes:

1. Device iOS version < 16.0 (app requires iOS 16+)

2. Not signed in to iCloud

3. TestFlight build expired (90-day limit)

Solutions:

• Update iOS to 16.0 or later

• Settings → [Your Name] → Sign in to iCloud

• Request new build from developer

---

Issue: "Sign in to iCloud" Alert on Launch

Symptom: App shows alert "Please sign in to iCloud to use TheCompanyApp".

Cause: Not authenticated to iCloud.

Solution:

1. Settings → [Your Name]

2. Sign in with Apple ID

3. Enable iCloud Drive

4. Restart app

---

Company Management

Issue: Company Not Appearing After Creation

Symptom: Created company but it doesn't show in companies list.

Causes:

1. Save failed (check for error alert)

2. Fetch request not refreshing

3. CloudKit sync pending

Solutions:

• Pull to refresh companies list

• Wait 10-30 seconds for CloudKit sync

• Restart app

• Check iCloud status (Settings → iCloud)

---

Issue: Cannot Switch Between Companies

Symptom: Tapping company does nothing or app crashes.

Cause: Core Data context issue or deleted company.

Solution:

• Force quit and reopen app

• If persists, delete app and reinstall (data preserved in iCloud)

---

Sharing

Issue: Share Link Not Working

Symptom: Participant taps share link, nothing happens.

Causes:

1. Link copied incorrectly (missing characters)

2. App not installed on participant's device

3. Participant not signed in to iCloud

4. Universal links not configured

Solutions:

• Participant: Install TheCompanyApp from TestFlight first

• Verify signed in to iCloud

• Copy link again from owner, ensure full URL

• Try opening URL in Safari manually → Should redirect to app

---

Issue: Participant Accepted Share but Company Not Showing

Symptom: Acceptance succeeded but company missing from list.

Causes:

1. CloudKit sync delay

2. Shared Database not syncing

3. iCloud Drive disabled for app

Solutions:

• Wait 1-2 minutes, pull to refresh

• Settings → iCloud → TheCompanyApp → Enable toggle

• Restart app

• Check Console.app logs for sync errors

---

Issue: "You Don't Have Permission to Edit"

Symptom: Participant tapped edit button, sees error.

Causes:

1. Owner set share permission to "View Only"

2. AccessControl denies edit permission

3. CloudKit share not fully synced

Solutions:

• Owner: Settings → Sharing → Change permission to "Can Edit"

• Owner: Update AccessControl for participant

• Wait 30 seconds for permission sync

---

Issue: Owner Can't See Participant's Changes

Symptom: Participant created order, owner doesn't see it.

Causes:

1. Participant's change not synced yet

2. Enlistment failed (object not in share)

3. Network issue on participant's device

Solutions:

• Owner: Pull to refresh, wait 1 minute

• Participant: Check internet connection, retry save

• Both: Restart app

• Check CloudKit Dashboard for record existence

---

Data Sync

Issue: Changes Not Syncing Across Devices (Same User)

Symptom: Created item on iPhone, doesn't appear on iPad (same Apple ID).

Causes:

1. Different iCloud accounts signed in

2. iCloud Drive disabled on one device

3. Network issue

4. CloudKit quota exceeded

Solutions:

• Verify same Apple ID on both devices

• Settings → iCloud → iCloud Drive → Enable on both

• Check Wi-Fi connection

• Settings → iCloud → Manage Storage → Check available space

---

Issue: Duplicate Entries After Sync

Symptom: Same company/order appears multiple times.

Cause: Conflict resolution issue or multiple accept of same share.

Solution:

• Delete duplicates manually

• If recurring, delete app, reinstall

• Report bug with CloudKit logs

---

Issue: "iCloud Storage Full" Error

Symptom: Save fails with quota exceeded error.

Cause: User's iCloud storage limit reached (5 GB free, more with paid plans).

Solutions:

• Settings → iCloud → Manage Storage → View what's using space

• Delete old backups, photos, files

• Upgrade iCloud storage plan

• Archive old companies in app (future feature)

---

Performance

Issue: App Slow to Load Companies

Symptom: Companies list takes > 5 seconds to appear.

Causes:

1. Large number of companies (100+)

2. Slow network

3. Core Data fetching all related data

Solutions:

• Use pagination (load 20 companies at a time)

• Archive inactive companies

• Check network speed

• Delete unused companies

---

Issue: High Battery Drain

Symptom: App uses significant battery even in background.

Cause: CloudKit background sync polling frequently.

Solution:

• Settings → General → Background App Refresh → Disable for TheCompanyApp

• Note: Disables background sync, data updates only when app open

---

Data Integrity

Issue: Missing Inventory Items

Symptom: Inventory items created yesterday are gone.

Causes:

1. Another user deleted them (in shared company)

2. Sync conflict resolved incorrectly

3. Data corruption

Solutions:

• Check with other company users (if shared)

• Review CloudKit Dashboard → Data → Records (verify deletion)

• If bug, report with reproduction steps

---

Issue: Order Status Reset

Symptom: Marked order as "Shipped", now shows "Pending" again.

Cause: Conflict resolution (another user edited offline, their change won).

Solution:

• Check updatedBy and updatedAt fields to see who/when changed

• Re-apply desired status

• Communicate with team to avoid concurrent edits

---

Login & Authentication

Issue: Face ID Not Working

Symptom: Face ID prompt doesn't appear on app launch.

Causes:

1. Face ID disabled in app settings

2. Face ID not set up on device

3. App preference not saved

Solutions:

• Settings (in app) → Security → Enable Face ID

• Settings (iOS) → Face ID & Passcode → Set up Face ID

• Restart app

---

Issue: "Incorrect Password" for UserPass

Symptom: Cannot log in with correct password.

Causes:

1. Password changed on another device (synced)

2. Typo in password

3. UserPass record corrupted

Solutions:

• Double-check password (case-sensitive)

• Reset password: Settings → Users → Edit User → Change Password

• If participant, delete and re-create UserPass

---

Crashes

Issue: App Crashes on Launch

Symptom: App opens, shows splash screen, crashes immediately.

Causes:

1. Core Data model corruption

2. CloudKit migration issue

3. iOS version incompatibility

Solutions:

• Restart device

• Delete app, reinstall from TestFlight

• If persists, send crash log to developer

Get Crash Log:

1. Settings → Privacy & Security → Analytics & Improvements

2. Analytics Data → Find "TheCompanyApp-..."

3. Share log file

---

Issue: Crash When Accepting Share

Symptom: Tap "Accept" on share prompt, app crashes.

Cause: CloudKit metadata parsing error or share URL malformed.

Solution:

• Restart app, retry accept

• Ask owner to re-send share link (regenerate)

• Report bug with share URL (redact sensitive parts)

---

Notifications

Issue: Not Receiving Notifications

Symptom: Other users create orders, no notification appears.

Causes:

1. Notifications disabled in iOS settings

2. App not implementing notifications (future feature)

3. CloudKit remote notifications not enabled

Solutions:

• Settings → TheCompanyApp → Notifications → Allow

• Background App Refresh → Enable

• Note: In-app notification system may not be fully implemented

---

Development/Testing

Issue: CloudKit Dashboard Shows No Records

Symptom: Created company in app, but CloudKit Dashboard shows 0 records.

Causes:

1. Using Development environment in app, viewing Production in Dashboard

2. Sync not completed yet

3. Account mismatch (different Apple ID)

Solutions:

• Dashboard → Select correct environment (Development vs Production)

• Wait 2-5 minutes for sync

• Verify same Apple ID in app and CloudKit Dashboard

---

Issue: "Zone Not Found" Error

Symptom: Error: CKErrorDomain Code=26: Zone not found.

Cause: CloudKit zone creation failed or schema reset.

Solutions:

• Delete app, reinstall (recreates zones)

• CloudKit Dashboard → Schema → Reset Development Environment

• Check Xcode logs for zone creation errors

---

Reset Options

Soft Reset (Preserve Data)

Purpose: Fix UI issues, refresh sync.

Steps:

1. Force quit app (swipe up in app switcher)

2. Reopen app

3. Pull to refresh

Data: Preserved in iCloud.

---

Hard Reset (Clear Local Data)

Purpose: Fix data corruption, test fresh install.

Steps:

1. Delete TheCompanyApp from device

2. Settings → General → iPhone Storage → TheCompanyApp → Delete App Data (if prompted)

3. Reinstall from TestFlight

Data: Re-downloads from iCloud on first launch.

---

Complete Reset (Delete All Data)

⚠️ WARNING: Permanently deletes all companies, inventory, orders.

Steps:

1. Delete all companies manually in app

2. Delete app from device

3. CloudKit Dashboard → Data → Delete all records (Development only)

Use Case: Testing only, not for production.

---

Reporting Bugs

Include:

1. iOS version

2. App version (Settings → About)

3. Steps to reproduce

4. Expected vs actual result

5. Screenshots or screen recording

6. Console.app logs (if possible)

Send to: Developer email or TestFlight feedback.

---

Related: Troubleshooting, Debugging Logs, Share Testing Checklist