Troubleshooting

Common issues and solutions for Sorolla SDK integration.

Quick Fixes

Issue Solution Details
SDK not initializing Check Assets/Resources/SorollaConfig.asset exists →
Events not appearing Verify SDK keys, wait 5-10 min →
Ads not loading Check SDK Key and Ad Unit IDs, wait 30 sec after init →
Remote config returns defaults Ensure values are published in console →
Firebase errors Verify config files match bundle ID →
Build failing Check Build Health in Configuration window →
Runtime crash on Android Open Palette > Configuration, check Build Health →
iOS provisioning errors Open Xcode, enable "Automatically manage signing" →

Build Health

The Configuration window includes a Build Health section that validates your SDK setup before building. It runs 6 technical checks:

Check What it validates
SDK Versions Installed versions meet minimum requirements
Mode Consistency Installed SDKs match current mode (Prototype/Full)
Scoped Registries UPM registries are properly configured
Firebase Coherence Firebase modules have FirebaseApp installed
Config Sync SorollaConfig matches installed packages
Android Manifest No orphaned SDK entries that cause crashes

Note: SDK installation status is shown in the SDK Overview section above Build Health.

Auto-fix: The validator automatically fixes AndroidManifest issues when the window opens or before builds.

Pre-build validation: Errors block builds automatically via IPreprocessBuildWithReport.

SDK Initialization

"SorollaConfig not found"

Cause: Config asset missing from Resources folder.

Fix:

  1. Open Sorolla > Configuration
  2. Click "Create Config" if prompted
  3. Verify Assets/Resources/SorollaConfig.asset exists

SDK not auto-initializing

Cause: SorollaBootstrapper not creating.

Fix:

  1. Check for compile errors in Console
  2. Verify Sorolla namespace accessible
  3. Ensure no other [RuntimeInitializeOnLoadMethod] conflicts

Analytics

Events not appearing in GameAnalytics

  1. Verify Game Key and Secret Key are correct
  2. Check Unity Editor console for errors
  3. Events may take 5-10 minutes to appear in dashboard
  4. Ensure GA account has Admin access

Events not appearing in Firebase

  1. Verify google-services.json (Android) or GoogleService-Info.plist (iOS) exists
  2. Enable "Google Analytics" when creating Firebase project
  3. Firebase events have ~24 hour delay in console

Ads (AppLovin MAX)

Ads not loading

  1. Verify SDK Key in Configuration window
  2. Check Ad Unit IDs (Rewarded, Interstitial)
  3. Wait 30 seconds after init for first ad load
  4. Check device has internet connection

Low fill rate

  1. Enable mediation networks in MAX dashboard
  2. Add AdMob, Meta, Unity Ads for better fill
  3. Test on real device (not editor/simulator)

Ad revenue not tracking

  1. Verify Adjust App Token (Full mode)
  2. Check Adjust is initialized (Debug UI > Health)
  3. Revenue reports may take 24 hours

Remote Config

Always returns default values

Firebase:

  1. Verify parameters are published in Firebase Console
  2. Call FetchRemoteConfig() before getting values
  3. Check Firebase config files present

GameAnalytics:

  1. Configure A/B tests in GA dashboard
  2. Ensure user is in test group

Fetch always fails

  1. Check internet connection
  2. Verify Firebase project setup
  3. Check Console for initialization errors

iOS-Specific Issues

CocoaPods/Ruby Errors

Error: gem install activesupport fails, ruby/config.h not found

Cause: System Ruby (2.6) missing headers.

Fix:

# Install CocoaPods via Homebrew
brew install cocoapods

# Verify installation
pod --version

# In Unity: switch platform to Android, then back to iOS
# This forces environment reload

ATT Dialog Not Showing

  1. Verify iOS 14.5+ target
  2. Check ContextScreen prefab in Resources
  3. ATT only shows once per app install
  4. Use Debug UI to reset consent for testing

Missing Provisioning Profile

  1. Open Xcode project
  2. Select Unity-iPhone target
  3. Enable "Automatically manage signing"
  4. Select your Apple Developer Team
  5. Connect device and let Xcode register it

Facebook SDK Swift Errors

Error: TournamentUpdater has no member 'update'

Cause: Facebook iOS SDK 18.0.2 breaking changes.

Fix: Pin Facebook pods to exactly 18.0.1 (not ~> 18.0.1).

Firebase "GoogleService-Info.plist not found"

  1. Download from Firebase Console > Project Settings > iOS app
  2. Place in Assets/ folder
  3. Bundle ID must match exactly

Android-Specific Issues

Build Health - AndroidManifest Errors

Error: ClassNotFoundException at runtime (e.g., com.facebook.FacebookContentProvider)

Cause: AndroidManifest.xml has entries for SDKs that are no longer installed.

How it happens: Switching modes (Prototype ↔ Full) can leave orphaned entries.

Fix:

  1. Open Palette > Configuration window
  2. Check the Build Health section
  3. If "Android Manifest" shows an error, it will be auto-fixed on next validation
  4. Or open Palette > Configuration and click Refresh in Build Health

The Build Health validator automatically detects and removes orphaned manifest entries before builds.

Wrong Main Activity Class

Error: ClassNotFoundException: com.unity3d.player.UnityPlayerGameActivity (or UnityPlayerActivity) at launch.

Cause: The AndroidManifest.xml declares an activity class that doesn't match the project's Application Entry Point setting in Player Settings.

Background: androidApplicationEntry in ProjectSettings.asset is a bitmask:

  • 1 = Activity (legacy UnityPlayerActivity)
  • 2 = GameActivity (UnityPlayerGameActivity) - Unity 6 default for new projects
  • 3 = both

Unity only compiles the selected entry point class into the APK. If the manifest references the wrong one, the class won't exist at runtime.

Common triggers:

  • Upgrading from Unity 2022 to Unity 6 (preserves Activity setting but manifest patchers may assume GameActivity)
  • Third-party SDK manifest patchers using #if UNITY_2023_1_OR_NEWER instead of reading the actual PlayerSettings value

Fix:

  1. Check Player Settings > Android > Other Settings > Application Entry Point
  2. Ensure AndroidManifest.xml activity class matches:
    • Activity: com.unity3d.player.UnityPlayerActivity
    • GameActivity: com.unity3d.player.UnityPlayerGameActivity
  3. If using useCustomLauncherManifest, check LauncherManifest.xml matches too
  4. Run Palette > Configuration - Build Health will detect and fix mismatches

LauncherManifest.xml Missing Activity (Unity 6)

Error: DeploymentOperationFailedException: No activity in the manifest with action MAIN and category LAUNCHER

Cause: When useCustomLauncherManifest is enabled in Player Settings, Unity uses LauncherManifest.xml for the launcher Gradle module. If this file lacks a launcher activity declaration, the app installs but cannot launch.

Background: Unity 6 uses a split Gradle module structure:

  • AndroidManifest.xml -> unityLibrary module (library)
  • LauncherManifest.xml -> launcher module

Unity generates android:enabled="false" on the non-selected activity in the library manifest. The launcher manifest must override this.

Fix: Ensure LauncherManifest.xml declares the correct activity with the launcher intent filter:

<activity android:name="com.unity3d.player.UnityPlayerGameActivity"
          android:theme="@style/BaseUnityGameActivityTheme"
          android:enabled="true"
          android:exported="true"
          tools:replace="android:enabled">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
    <meta-data android:name="android.app.lib_name" android:value="game" />
</activity>

Replace UnityPlayerGameActivity/BaseUnityGameActivityTheme with UnityPlayerActivity/UnityThemeSelector if using legacy Activity mode.

Note: Unity's deployment checker may still report this error even when the APK is correct, because it reads source manifests rather than the Gradle-merged result. If the build succeeds, try installing the APK manually via adb install.

R8/AGP Version Mismatch

Error: NoSuchMethodError: setBuildMetadataConsumer or similar R8 crash during dexing.

Cause: A pinned R8 version in baseProjectTemplate.gradle conflicts with the AGP version.

Background:

  • Unity 2022 (AGP 7.4.2): Needs R8 8.1.56+ pin for Kotlin 2.0 metadata from libraries like AppLovin SDK 13.x and Firebase 23.x
  • Unity 6 (AGP 8.10.0): Bundled R8 already handles Kotlin 2.0 - the pin must be REMOVED

Fix:

  1. Open Assets/Plugins/Android/baseProjectTemplate.gradle
  2. If upgrading TO Unity 6: remove the entire buildscript { ... } block that pins R8
  3. If on Unity 2022 with Kotlin 2.0 libraries: add the R8 pin:
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools:r8:8.1.56"
    }
}

Gradle/Java Error on First Import

Error: NoClassDefFoundError: org.codehaus.groovy.vmplugin.v7.Java7 or similar Gradle/Java stacktrace on first Android resolve.

Cause: EDM4U bundles Gradle 5.1.1 which only supports Java 8-12. Unity 6+ uses Java 17+ by default. On first import, EDM4U may auto-resolve before Palette configures it to use Unity's Gradle.

Fix: This is cosmetic - restart Unity and it resolves automatically. Palette configures EDM4U to use Unity's Gradle templates on every domain reload. If the error persists:

  1. Run Palette > Run Setup (Force)
  2. Or manually enable Gradle templates: Assets > External Dependency Manager > Android Resolver > Settings -> check all "Patch ... Template" options

Gradle Version Mismatch

Error: Incompatible Gradle version

Fix:

  1. Export to Android Studio
  2. Update gradle-wrapper.properties to Gradle 8.0+
  3. Build from Android Studio

Missing google-services.json

  1. Download from Firebase Console > Project Settings > Android app
  2. Place in Assets/ or Assets/Plugins/Android/
  3. Package name must match exactly

Firebase Issues

Android crash: "Default FirebaseApp failed to initialize"

Error: FirebaseApp: Default FirebaseApp failed to initialize because no default options were found. This usually means that com.google.gms:google-services was not applied to your gradle project.

Cause: Assets/Plugins/Android/FirebaseApp.androidlib/ is missing. This folder is auto-generated by Firebase's Editor scripts (Firebase.Editor.dll) from your google-services.json. It contains the processed Android resources that Firebase needs at runtime.

Common triggers:

  • First import of Firebase packages (Editor scripts haven't run yet)
  • Switching SDK reference from local symlink to UPM git URL
  • Deleting the Library folder and reimporting

Fix:

  1. Ensure google-services.json is in Assets/
  2. Trigger a domain reload (make a small C# edit, or Edit > Preferences > Script Changes While Playing > Recompile After Finished Playing)
  3. Check Assets/Plugins/Android/ for FirebaseApp.androidlib/ - it should appear after reload
  4. If still missing: Assets > External Dependency Manager > Android Resolver > Force Resolve
  5. Verify FirebaseApp.androidlib/res/values/google-services.xml exists and contains your Firebase project values

Also check: FirebaseCrashlytics.androidlib/ should appear alongside it if Crashlytics is installed.

"Firebase not initialized"

  1. Check config files present and matching bundle ID
  2. Verify internet connection on first launch
  3. Check Console for async init errors

Crashlytics not reporting

  1. Crashes report on next app launch
  2. Wait 5-10 minutes for dashboard update
  3. Verify Firebase config files are in Assets/

Crashes in development not showing

Crashlytics requires:

  1. Release build (not debug)
  2. App restart after crash
  3. Internet connection

Editor Issues

Configuration window not opening

  1. Menu: Sorolla > Configuration
  2. If missing, check for compile errors
  3. Try Window > Package Manager > Sorolla SDK > Reimport

SDK detection failing

  1. Close Unity completely
  2. Delete Library/ folder
  3. Reopen project
  4. Let packages reimport

Mode switch not working

  1. Confirm dialog appears
  2. Wait for package manager to finish
  3. Unity may need restart for scripting defines

Debug UI

Debug panel not appearing

  1. Import sample from Package Manager
  2. Add DebugPanelManager prefab to scene
  3. Triple-tap (mobile) or BackQuote key (desktop)
  4. Check prefab is DontDestroyOnLoad

Health indicators red

  • GA: Check Game Key/Secret Key
  • MAX: Check SDK Key and Ad Unit IDs
  • Adjust: Check App Token (Full mode only)
  • Firebase: Check config files present

Getting Help

  1. Check GitHub Issues
  2. Review error messages in Unity Console
  3. Use Debug UI for on-device diagnostics
  4. File new issue with:
    • Unity version
    • SDK version
    • Platform (iOS/Android)
    • Full error message
    • Steps to reproduce
Edit this page