Troubleshooting Guide

Common issues and solutions for the iOS Starter Kit.

Build Issues
Runtime Issues
Authentication Issues
Backend Issues
Subscription Issues
Network Issues
Debugging Tips
Getting Help

Build Issues

❌ "No such module 'Authentication'" (or other module)

Symptoms: Build fails with error about missing module.

Causes:

Xcode's derived data is corrupted
Framework not properly linked
Opened .xcodeproj instead of .xcworkspace

Solutions:

Clean derived data:

# Close Xcode first
rm -rf ~/Library/Developer/Xcode/DerivedData

# Reopen workspace
open iOSJumpstart.xcworkspace

Clean build folder in Xcode:

Product → Clean Build Folder (⇧⌘K)

Verify you opened workspace:

# Always use .xcworkspace
open iOSJumpstart.xcworkspace

# NOT this:
# open Src/iOSJumpstart/iOSJumpstart.xcodeproj

Check framework linking:

Select project → Target → General
Scroll to "Frameworks, Libraries, and Embedded Content"
Ensure all feature frameworks are present

❌ "Signing for iOSJumpstart requires a development team"

Symptoms: Build fails with signing error.

Solution:

In Xcode, select project → iOSJumpstart target → Signing & Capabilities
Team dropdown → Select your Apple Developer Account
If not listed:
- Xcode → Settings (⌘,)
- Accounts tab
- Click (+) → Apple ID
- Sign in with your Apple Developer credentials
- Ensure enrollment is Active (not just created)

❌ Build fails with SwiftData errors

Symptoms: Errors about @Model, ModelContext, or PersistentModel.

Cause: iOS deployment target too low.

Solution:

Select project → iOSJumpstart target → General
Deployment Info → iOS → Set to 17.0 or later
Clean and rebuild

❌ "Type 'Factory' has no member 'shared'"

Symptoms: Factory dependency injection not working.

Cause: Factory package not imported or outdated.

Solution:

Check Package Dependencies:
- File → Packages → Resolve Package Versions
Ensure Factory is added:
- Project → Package Dependencies
- Should see Factory package
Import in files:

import Factory

❌ Build succeeds but app crashes immediately

See: Runtime Issues section below.

Runtime Issues

❌ App crashes on launch with no error

Symptoms: App installs but crashes immediately on launch.

Debugging Steps:

Open Console (⇧⌘Y in Xcode)
Look for error messages in red
Common errors and solutions below

❌ "Could not load AppConfiguration"

Symptoms:

Fatal error: Could not find AppConfiguration.Supabase.url

Cause: AppConfiguration.swift missing or not in target.

Solution:

Check file exists:

ls -l Src/Features/Common/Common/Configuration/AppConfiguration.swift

If missing, create it:

cd Src/Features/Common/Common/Configuration/
cp AppConfiguration.template AppConfiguration.swift
# Edit and fill in your credentials

Verify target membership:
- Select AppConfiguration.swift in Xcode
- File Inspector (right panel)
- Target Membership: Check Common

❌ "Supabase URL or key is invalid"

Symptoms: App crashes or authentication fails with Supabase error.

Solution:

Verify credentials in AppConfiguration.swift:

public enum Supabase {
    public static let url = "https://YOUR_PROJECT_ID.supabase.co"
    public static let anonKey = "eyJhbGciOiJIUzI1NiIsIn..."
}

Get correct values:
- Go to app.supabase.com
- Select your project
- Settings → API
- Copy Project URL and anon public key
Ensure no trailing slashes in URL

❌ "GoogleService-Info.plist not found"

Symptoms: Firebase initialization fails.

Cause: Missing or incorrectly placed Firebase config file.

Solution:

Download from Firebase Console:
- console.firebase.google.com
- Select project → iOS app
- Download GoogleService-Info.plist
Add to project:

# Copy to correct location
cp ~/Downloads/GoogleService-Info.plist \
   Src/iOSJumpstart/iOSJumpstart/GoogleService-Info.plist

Verify in Xcode:
- Select GoogleService-Info.plist
- File Inspector → Target Membership
- Check iOSJumpstart

Authentication Issues

❌ Apple Sign-In fails with "Invalid Bundle ID"

Symptoms: Sign in with Apple shows error or doesn't work.

Cause: Bundle ID mismatch between app and Apple Developer Portal.

Solution:

Verify Bundle ID in Xcode:
- Project → Target → Signing & Capabilities
- Note the Bundle Identifier (e.g., com.yourcompany.app)
Check Apple Developer Portal:
- Go to developer.apple.com/account/resources/identifiers
- Find your App ID
- Verify Bundle ID matches exactly
Check Capabilities:
- In Xcode: Signing & Capabilities
- Ensure Sign in with Apple capability is added
- Check iOSJumpstart.entitlements file contains:

<key>com.apple.developer.applesignin</key>
<array>
    <string>Default</string>
</array>

❌ Google Sign-In fails or doesn't redirect back

Symptoms: Google OAuth opens but doesn't return to app.

Common Causes & Solutions:

1. Wrong Client ID in Info.plist:

Check Src/iOSJumpstart/iOSJumpstart/Info.plist:

<key>GIDClientID</key>
<string>YOUR_IOS_CLIENT_ID.apps.googleusercontent.com</string>

Should match the iOS Client ID from Google Cloud Console.

2. Incorrect URL Scheme:

In Info.plist, find CFBundleURLTypes → CFBundleURLSchemes:

<key>CFBundleURLSchemes</key>
<array>
    <string>com.googleusercontent.apps.YOUR_CLIENT_ID</string>
</array>

This should be your iOS Client ID reversed (remove the .apps.googleusercontent.com and add com.googleusercontent.apps. prefix).

Example:

iOS Client ID: 123456789-abc.apps.googleusercontent.com
URL Scheme: com.googleusercontent.apps.123456789-abc

3. Wrong Client ID in AppConfiguration.swift:

public enum Google {
    // This should be iOS Client ID
    public static let clientID = "123456789-abc.apps.googleusercontent.com"
}

4. Supabase Google Provider not configured:

Go to Supabase Dashboard → Authentication → Providers → Google
Ensure it's Enabled
Client ID: Should be Web Client ID (not iOS!)
Client Secret: From Web Client creation
Authorized Client IDs: Add your iOS Client ID

❌ "User session not found after login"

Symptoms: Login completes but app still shows auth screen.

Debugging:

Check Xcode Console for errors
Verify RootViewModel state updates:

// In RootViewModel.swift
func checkAuthStatus() async {
    // Should emit userLoggedIn event
}

Check EventViewModel is receiving events:

// Add debug logging
eventViewModel.emit(.userLoggedIn)
print("[DEBUG] User logged in event emitted")

Backend Issues

❌ "RLS policy violation" or "permission denied"

Symptoms: Database queries fail with RLS (Row-Level Security) error.

Cause: Missing or incorrect RLS policies in Supabase.

Solution:

Check you're authenticated:

let user = try await supabase.auth.session.user
print("User ID: \(user.id)")

Verify RLS policies in Supabase Dashboard:
- Database → Policies → profiles table
- Should have policies for SELECT, INSERT, UPDATE, DELETE
- Policies should check auth.uid() = id
Re-run SQL from SUPABASE_SETUP_GUIDE.md:

-- Enable RLS
alter table public.profiles enable row level security;

-- Policy: Users can read their own profile
create policy "Users can update own profile."
  on profiles for update
  using ( auth.uid() = id );

❌ Avatar upload fails with "Bucket not found"

Symptoms: File upload fails with error about missing bucket.

Cause: Storage bucket not created or misconfigured.

Solution:

Check bucket exists:
- Supabase Dashboard → Storage
- Should see bucket named storage
Create bucket if missing:

insert into storage.buckets (id, name, public)
values ('storage', 'storage', true);

Verify RLS policies for storage:
- Storage → Policies
- Should have policies for SELECT, INSERT, UPDATE, DELETE on avatars/ folder
Check bucket name in code:

// Should be "storage", not "avatars"
let bucketName = "storage"
let path = "avatars/\(userId).jpg"

❌ Profile not created on signup

Symptoms: User signs up but no profile row in database.

Cause: Database trigger not working.

Solution:

Check trigger exists:
- Supabase Dashboard → Database → Triggers
- Should see on_auth_user_created trigger
Re-create trigger:

-- Function
create or replace function public.handle_new_user()
returns trigger
language plpgsql
security definer set search_path = public
as $$
begin
  insert into public.profiles (id, email, full_name, avatar_url)
  values (
    new.id,
    new.raw_user_meta_data ->> 'email',
    new.raw_user_meta_data ->> 'full_name',
    new.raw_user_meta_data ->> 'avatar_url'
  );
  return new;
end;
$$;

-- Trigger
drop trigger if exists on_auth_user_created on auth.users;
create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

Test by creating a new user

Subscription Issues

❌ RevenueCat shows "No products available"

Symptoms: Paywall shows no products or products list is empty.

Causes & Solutions:

1. API Key mismatch:

Check AppConfiguration.swift:

public enum RevenueCat {
    #if DEBUG
    public static let apiKey = "test_..." // For sandbox
    #else
    public static let apiKey = "appl_..." // For production
    #endif
}

2. Products not created:

Go to app.revenuecat.com
Projects → Your Project → Products
Create products for your app

3. Products not attached to offering:

RevenueCat Dashboard → Offerings
Create an offering (e.g., "default")
Add packages and attach products

4. StoreKit configuration not loaded:

In Xcode:

Editor → Default Transaction → StoreKit Configuration File
Select Products.storekit

❌ "Entitlement not found"

Symptoms: Subscription check fails with entitlement error.

Solution:

Verify entitlement ID:
- RevenueCat Dashboard → Entitlements
- Note the identifier (e.g., "pro")
Update AppConfiguration.swift:

public enum RevenueCat {
    public static let entitlementID = "pro" // Must match exactly
}

❌ Purchase fails in sandbox

Symptoms: Sandbox purchases don't complete.

Common Issues:

Not signed in to sandbox account:
- Settings → App Store → Sandbox Account
- Sign in with test account from App Store Connect
Test account not created:
- App Store Connect → Users and Access → Sandbox Testers
- Create test account
StoreKit config issues:
- Ensure Products.storekit has products defined
- Products match RevenueCat configuration

Network Issues

❌ Network banner always shows "No Connection"

Symptoms: Red banner always visible even with internet.

Debugging:

Check simulator network:
- Simulator → Settings → Wi-Fi
- Ensure Wi-Fi is enabled and connected
Restart NetworkMonitor:
- Stop app (⌘.)
- Clean build folder (⇧⌘K)
- Run again (⌘R)
Check NetworkMonitor implementation:

// Should detect network status
print("Network connected: \(networkMonitor.isConnected)")

❌ App update checker not working

Symptoms: Force update overlay doesn't appear when it should.

Causes & Solutions:

1. App Store ID not set:

Update AppConfiguration.swift:

public enum App {
    // Get from App Store Connect
    public static let appStoreID = "1234567890"
}

2. Version format incorrect:

Check Info.plist:

<key>CFBundleShortVersionString</key>
<string>1.0.0</string>  <!-- Should be semantic version -->

3. iTunes API not responding:

Only works for apps published on App Store
In development, use mock data for testing

Debugging Tips

Enable Verbose Logging

Add to AppConfiguration.swift:

public enum Debug {
    #if DEBUG
    public static let enableLogging = true

    public static func log(_ message: String, file: String = #file, function: String = #function, line: Int = #line) {
        if enableLogging {
            let filename = (file as NSString).lastPathComponent
            print("[\(filename):\(line)] \(function) - \(message)")
        }
    }
    #endif
}

Use in code:

#if DEBUG
AppConfiguration.Debug.log("User signed in: \(user.id)")
#endif

Debug Supabase Requests

// In SupabaseClient configuration
let client = SupabaseClient(
    supabaseURL: URL(string: AppConfiguration.Supabase.url)!,
    supabaseKey: AppConfiguration.Supabase.anonKey,
    options: .init(
        auth: .init(debug: true)  // Enable auth debug logs
    )
)

Debug RevenueCat

// In AppDelegate or App initialization
import RevenueCat

Purchases.logLevel = .debug  // Enable verbose logging

Test Without Services

Comment out service initialization to isolate issues:

// In AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions...) {
    // FirebaseApp.configure()  // Commented out for testing
    // RevenueCat setup // Commented out
}

Use Breakpoints

Set breakpoints in key locations:

RootViewModel.swift:45 - Auth state changes
AuthRepository.swift:120 - Sign-in methods
SubscriptionManager.swift:89 - Subscription checks

Inspect UserDefaults

// Check what's stored
let defaults = UserDefaults.standard
print("Has seen onboarding: \(defaults.bool(forKey: "hasSeenOnboarding"))")
print("Dark mode: \(defaults.bool(forKey: "isDarkMode"))")

Reset Simulator

If all else fails:

Reset simulator:
- Simulator → Device → Erase All Content and Settings
Delete app and rebuild:

# Clean build
rm -rf ~/Library/Developer/Xcode/DerivedData

# Rebuild
open iOSJumpstart.xcworkspace
# Product → Clean Build Folder
# Product → Build
# Product → Run

Getting Help

Before Asking for Help

✅ Check this troubleshooting guide
✅ Review SETUP.md for setup issues
✅ Check ARCHITECTURE.md for architecture questions
✅ Search existing issues
✅ Enable debug logging and gather error messages

How to Ask for Help

When opening an issue, include:

Environment:
- Xcode version
- iOS version (simulator/device)
- macOS version
Steps to reproduce:
- What you did
- What you expected
- What actually happened
Error messages:
- Console output
- Screenshots
- Crash logs
What you've tried:
- Solutions attempted
- Results

Support Channels

🐛 Bug Reports: GitHub Issues
💬 Questions: GitHub Discussions
📧 Email: support@yourapp.com

Common Error Messages Reference

Error	Likely Cause	See Section
"No such module"	Derived data issue	Build Issues
"Signing requires team"	Missing Apple Developer account	Build Issues
"RLS policy violation"	Missing database policies	Backend Issues
"Bucket not found"	Storage not configured	Backend Issues
"Invalid Bundle ID"	Bundle ID mismatch	Authentication Issues
"No products available"	RevenueCat not configured	Subscription Issues
"Network not available"	NetworkMonitor issue	Network Issues

Still stuck? Open an issue with details, and we'll help you out! 🚀

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting Guide

Table of Contents

Build Issues

❌ "No such module 'Authentication'" (or other module)

❌ "Signing for iOSJumpstart requires a development team"

❌ Build fails with SwiftData errors

❌ "Type 'Factory' has no member 'shared'"

❌ Build succeeds but app crashes immediately

Runtime Issues

❌ App crashes on launch with no error

❌ "Could not load AppConfiguration"

❌ "Supabase URL or key is invalid"

❌ "GoogleService-Info.plist not found"

Authentication Issues

❌ Apple Sign-In fails with "Invalid Bundle ID"

❌ Google Sign-In fails or doesn't redirect back

❌ "User session not found after login"

Backend Issues

❌ "RLS policy violation" or "permission denied"

❌ Avatar upload fails with "Bucket not found"

❌ Profile not created on signup

Subscription Issues

❌ RevenueCat shows "No products available"

❌ "Entitlement not found"

❌ Purchase fails in sandbox

Network Issues

❌ Network banner always shows "No Connection"

❌ App update checker not working

Debugging Tips

Enable Verbose Logging

Debug Supabase Requests

Debug RevenueCat

Test Without Services

Use Breakpoints

Inspect UserDefaults

Reset Simulator

Getting Help

Before Asking for Help

How to Ask for Help

Support Channels

Common Error Messages Reference