Skip to main content

​
Development Troubleshooting Guide

Common issues encountered during Sanctiv app development and their solutions.

​
iOS Build Issues

​
Swift API Compatibility: onGeometryChange Not Available

Symptom: 
error: value of type 'some View' has no member 'onGeometryChange'
  in node_modules/expo-modules-core/ios/Core/Views/SwiftUI/AutoSizingStack.swift
Root Cause:
  • Expo SDK 53’s expo-modules-core uses onGeometryChange SwiftUI API
  • This API was introduced in iOS 18.0
  • Build fails when using Xcode versions older than 16.0 (which lack iOS 18 SDK)
Solution (CI/CD): Upgrade to Xcode 16.0+ in your GitHub Actions workflow: 
- name: Setup Xcode 16.1
  run: sudo xcode-select -s /Applications/Xcode_16.1.app
Solution (Local Development): Ensure you have Xcode 16.0+ installed: 
# Check current Xcode version
xcodebuild -version

# If needed, download Xcode 16.1 from:
# https://developer.apple.com/download/applications/

# Set as active version
sudo xcode-select -s /Applications/Xcode_16.1.app

# Verify iOS 18 SDK is available
xcodebuild -showsdks | grep iphoneos
Related:

​
Dependency Management

​
Lockfile Out of Sync

Symptom:
  • CI builds fail despite updating package.json
  • Installed packages don’t match versions in package.json
  • expo doctor shows warnings about mismatched versions
Root Cause:
  • bun.lock (lockfile) wasn’t regenerated after updating package.json
  • Package managers install versions from lockfile, not package.json
Solution: 
# Regenerate lockfile
bun install

# Verify lockfile is updated
git diff bun.lock

# Commit both files together
git add package.json bun.lock
git commit -m "fix(deps): update dependencies and regenerate lockfile"
Best Practice: Always run bun install after modifying package.json, even if just changing version numbers.

​
CI/CD Issues

​
Xcode Version Selection in GitHub Actions

Context: GitHub Actions macos-14 runners come with multiple Xcode versions pre-installed but default to an older version. Available Versions (macos-14):
  • Xcode 14.3.1
  • Xcode 15.0.1
  • Xcode 15.4 (default)
  • Xcode 16.0
  • Xcode 16.1
How to Select Specific Version: 
steps:
  - name: Setup Xcode 16.1
    run: sudo xcode-select -s /Applications/Xcode_16.1.app
Verify Selection: 
  - name: Verify Xcode version
    run: |
      xcodebuild -version
      xcodebuild -showsdks | grep iphoneos
Documentation:

​
Testing

​
E2E Tests Failing Locally

Symptom: Maestro E2E tests pass in CI but fail locally Common Causes:
  1. iOS Simulator Not Running: 
    # Check if simulator is booted
xcrun simctl list devices | grep Booted

# Boot simulator if needed
xcrun simctl boot "iPhone 15 Pro"
  2. App Not Installed: 
    # Build and install app
bun run ios
  3. Maestro CLI Not Installed: 
    # Install Maestro
curl -Ls "https://get.maestro.mobile.dev" | bash

# Verify installation
maestro --version
Running E2E Tests: 
# Smoke tests (fast subset)
bun run test:e2e:smoke

# Full test suite
bun run test:e2e

​
Development Server

​
Port 8081 Already in Use

Context: Expo uses port 8081 by default for the development server. Solution: If port 8081 is already in use:
  1. Find the process using the port: 
    lsof -i :8081
  2. Kill the process if it’s not needed: 
    kill -9 <PID>
  3. Or restart the Expo server: 
    bun start

​
Expo / Metro Bundler

​
”Unable to resolve module” Errors

Solution: 
# Clear all caches
rm -rf node_modules
rm -rf .expo
rm -rf ios/build
rm -rf android/build

# Clean Metro bundler cache
bun start --clear

# Reinstall dependencies
bun install

# Rebuild iOS
cd ios && pod install && cd ..
bun run ios

​
Git Workflow

​
Remote Configuration

Context: Sanctiv uses GitHub for version control. Verify Remote: 
git remote -v
# Should show origin remote
Standard Push: 
git push origin main

​
Additional Resources

Last Updated: 2025-11-08
Maintainer: Development Team