---
updatedAt: 2026-10-14T08:58:16.000Z
agentTools:
  projectIndex: https://kasookoo-dev.readme.io/llms.txt
---

# TroubleShooting

# Troubleshooting Guide

Common issues with the Kasookoo Android SDK and how to resolve them.

***

## Table of Contents

1. [Installation Issues](#installation-issues)
2. [Build Errors](#build-errors)
3. [Authentication Errors](#authentication-errors)
4. [Connection Issues](#connection-issues)
5. [Call Issues](#call-issues)
6. [Audio Issues](#audio-issues)
7. [Push Notification Issues](#push-notification-issues)
8. [Performance Issues](#performance-issues)
9. [Debugging Tools](#debugging-tools)

***

## Installation Issues

### "Could not find com.kasookoo:sdk-android"

**Cause:** Maven repository not added or sync failed.

**Solutions:**

1. Verify Maven repository in `settings.gradle.kts`:
   ```kotlin
   maven {
       url = uri("https://maven.kasookoo.ai/releases")
   }
   ```

2. Click **Sync Project with Gradle Files** (toolbar refresh icon)

3. **File → Invalidate Caches & Restart**

4. Try CLI sync:
   ```bash
   ./gradlew clean
   ./gradlew build --refresh-dependencies
   ```

### "Manifest merger failed"

**Cause:** Conflicting permissions or services from different libraries.

**Solutions:**

1. Check error message for the specific conflict

2. Use `tools:replace` in your manifest:
   ```xml
   <application
       tools:replace="android:icon,android:label"
       ... >
   ```

3. Use `tools:remove` to remove conflicts:
   ```xml
   <service
       android:name="conflicting.service"
       tools:node="remove" />
   ```

### "Failed to resolve: com.google.firebase:firebase-bom"

**Solutions:**

1. Add Google Maven repository:
   ```kotlin
   repositories {
       google()
       mavenCentral()
   }
   ```

2. Verify internet connection and Maven Central access

3. Try using specific Firebase versions instead of BoM temporarily

***

## Build Errors

### "Duplicate class found in modules"

**Cause:** Multiple versions of the same dependency.

**Solutions:**

1. Run dependency tree:
   ```bash
   ./gradlew :app:dependencies
   ```

2. Exclude conflicting transitive dependencies:
   ```kotlin
   implementation("com.kasookoo:sdk-android:1.0.0") {
       exclude(group = "com.squareup.okhttp3")
   }
   ```

3. Force specific versions:
   ```kotlin
   configurations.all {
       resolutionStrategy {
           force("com.squareup.okhttp3:okhttp:4.12.0")
       }
   }
   ```

### "Cannot inline bytecode built with JVM target 1.8 into bytecode that is being built with JVM target 17"

**Cause:** Mixed JVM target versions.

**Solution:** Ensure all modules use JVM 17:

```kotlin
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = "17"
    }
}
```

### Build fails with R8/ProGuard errors

**Cause:** Code minification removing SDK classes.

**Solution:** Add ProGuard rules in `proguard-rules.pro`:

```proguard
-keep class com.kasookoo.sdk.** { *; }
-keep interface com.kasookoo.sdk.** { *; }
-dontwarn com.kasookoo.sdk.**

-keep class io.livekit.android.** { *; }
-dontwarn io.livekit.android.**

-keep class org.webrtc.** { *; }
-dontwarn org.webrtc.**
```

### "Class XYZ not found"

**Solutions:**

1. Clean build: **Build → Clean Project**
2. Rebuild: **Build → Rebuild Project**
3. Invalidate caches: **File → Invalidate Caches & Restart**

***

## Authentication Errors

### "Invalid publishable key"

**Symptoms:** `KasookooError.InvalidKey` thrown during `initialize()`

**Causes:**

* Wrong key format
* Expired key
* Wrong environment

**Solutions:**

1. Verify key format:
   * Sandbox: starts with `pk_test_`
   * Production: starts with `pk_live_`

2. Check key in [Kasookoo Dashboard](https://dashboard.kasookoo.ai):
   * Make sure key isn't revoked
   * Match environment to key type

3. Use correct environment in config:
   ```kotlin
   KasookooConfig(
       publishableKey = "pk_test_...",
       environment = Environment.SANDBOX
   )
   ```

### "Session expired" / 401 Unauthorized

**Symptoms:** API calls fail after working initially

**Causes:**

* Session TTL exceeded (default 10 minutes)
* Token refresh failed
* Backend session invalidated

**Solutions:**

1. SDK should auto-refresh. Check Logcat for refresh attempts.

2. Re-connect explicitly:
   ```kotlin
   lifecycleScope.launch {
       sdk.disconnect()
       sdk.connect()
   }
   ```

3. Re-initialize if needed:
   ```kotlin
   lifecycleScope.launch {
       sdk.destroy()
       sdk.initialize(config)
       sdk.connect()
   }
   ```

### "User identification failed"

**Causes:**

* Invalid email format
* Backend rejected user data
* User type mismatch

**Solutions:**

1. Validate email before sending:
   ```kotlin
   if (!email.contains("@")) return
   ```

2. Use valid `ParticipantType`:
   * `CUSTOMER`, `AGENT`, `DRIVER`, `BOT`, `ADMIN`

3. Check Logcat for specific rejection reason.

***

## Connection Issues

### "Failed to connect to backend"

**Symptoms:** `connect()` throws network exception

**Causes:**

* No internet connection
* Firewall blocking traffic
* Backend down
* Invalid base URL

**Solutions:**

1. Check internet connection:
   ```bash
   adb shell ping -c 4 sdk.kasookoo.ai
   ```

2. Verify environment URL:
   ```kotlin
   // Sandbox
   environment = Environment.SANDBOX  // → https://sdk-sandbox.kasookoo.ai

   // Production
   environment = Environment.PRODUCTION  // → https://sdk.kasookoo.ai
   ```

3. Check [status.kasookoo.ai](https://status.kasookoo.ai) for outages

4. Check firewall — allow these domains:
   * `*.kasookoo.ai`
   * `*.livekit.cloud`
   * `*.googleapis.com` (Firebase)

### "Token refresh failed repeatedly"

**Symptoms:** App keeps disconnecting

**Causes:**

* Clock skew (device time wrong)
* Backend changed JWT signing key
* Network instability

**Solutions:**

1. Verify device time is correct (Settings → Date & Time → Automatic)

2. Reset SDK state:
   ```kotlin
   lifecycleScope.launch {
       sdk.destroy()
       sdk.initialize(config)
   }
   ```

3. If issue persists, contact support with logs.

### "CleartextTrafficException"

**Cause:** App tries to use HTTP instead of HTTPS.

**Solutions:**

1. Use HTTPS endpoints only (Kasookoo enforces HTTPS by default)
2. If you must allow cleartext for debugging:
   ```xml
   <!-- AndroidManifest.xml -->
   <application
       android:usesCleartextTraffic="true"
       ... >
   ```

⚠️ Never use cleartext in production.

***

## Call Issues

### "Call fails immediately after start()"

**Symptoms:** Call goes from `INITIATING` to `FAILED`

**Causes:**

* Invalid callee
* Backend rejected call
* Insufficient permissions

**Solutions:**

1. Check error details:
   ```kotlin
   lifecycleScope.launch {
       sdk.events
           .filter { it.name == EventName.CALL_FAILED }
           .collect { event ->
               Log.e("Call", "Error: ${event.data["errorMessage"]}")
           }
   }
   ```

2. Verify callee has required info (name, email)

3. Check publishable key scopes include `webrtc`

### "Invalid state transition: X → Y"

**Symptoms:** Call state machine error

**Causes:**

* Calling `end()` on already-ended call
* Calling `accept()` on outgoing call
* Race condition

**Solutions:**

1. Check call state before action:
   ```kotlin
   if (call.state != CallState.ENDED && call.state != CallState.FAILED) {
       sdk.call.end(callId = call.id)
   }
   ```

2. Use SDK events to know when actions are valid

### "LiveKit connection failed"

**Symptoms:** Call reaches `CONNECTING` then fails

**Causes:**

* LiveKit token expired
* Network blocking WebRTC
* LiveKit cloud issues

**Solutions:**

1. Verify network allows WebRTC:
   * UDP 50000-60000 outbound
   * TCP 443 outbound
   * TURN servers reachable

2. Test on different network (cellular vs WiFi)

3. Check [LiveKit status](https://status.livekit.io)

***

## Audio Issues

### "Call connects but no audio"

**Symptoms:** State is `CONNECTED` but can't hear/be heard

**Causes:**

* Microphone permission denied
* Audio focus not granted
* Bluetooth routing issue
* Emulator (limited audio support)

**Solutions:**

1. Check microphone permission:
   ```kotlin
   if (ContextCompat.checkSelfPermission(
           this, 
           Manifest.permission.RECORD_AUDIO
       ) != PackageManager.PERMISSION_GRANTED
   ) {
       requestPermissions.launch(arrayOf(Manifest.permission.RECORD_AUDIO))
   }
   ```

2. **Test on real device** — emulator has limited audio

3. Check audio mode:
   ```kotlin
   val audioManager = getSystemService(AUDIO_SERVICE) as AudioManager
   Log.d("Audio", "Mode: ${audioManager.mode}")
   Log.d("Audio", "Speaker: ${audioManager.isSpeakerphoneOn}")
   ```

4. Force speaker output:
   ```kotlin
   audioManager.mode = AudioManager.MODE_IN_COMMUNICATION
   audioManager.isSpeakerphoneOn = true
   ```

### "Audio cuts in and out / poor quality"

**Causes:**

* Weak network signal
* Bandwidth constraints
* Background tasks consuming CPU

**Solutions:**

1. Test on stable WiFi
2. Close other apps using camera/microphone
3. Check network speed (need 100 kbps+ stable)
4. Update to latest LiveKit version

### "Echo / feedback during call"

**Causes:**

* Both devices' speakers near each other
* Echo cancellation not working

**Solutions:**

1. Use headphones on at least one device during testing
2. Increase distance between devices
3. Lower speaker volume
4. Verify echo cancellation is enabled in audio session

### "Bluetooth headphones not working"

**Solutions:**

1. Add BLUETOOTH\_CONNECT permission (Android 12+):
   ```xml
   <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
   ```

2. Request runtime permission:
   ```kotlin
   if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
       requestPermissions.launch(arrayOf(Manifest.permission.BLUETOOTH_CONNECT))
   }
   ```

***

## Push Notification Issues

### "FCM token not generated"

See [Push Notifications Guide](guides/push-notifications.md#issue-no-fcm-token-received).

### "Push received but no ConnectionService UI"

**Causes:**

* Payload format incorrect
* Phone account not registered
* MANAGE\_OWN\_CALLS permission missing

**Solutions:**

1. Verify payload includes:
   ```json
   {
     "data": {
       "type": "incoming_call",
       "call_id": "...",
       "room_name": "...",
       "caller_name": "..."
     }
   }
   ```

2. Register phone account at app startup (see Push Notifications Guide)

3. Verify permissions in Manifest

### "Push works in foreground but fails in background"

**Causes:**

* Battery optimization killing app
* Doze mode interfering
* Manufacturer-specific app management

**Solutions:**

1. Use `priority: "high"` in FCM payload

2. Request battery optimization exception:
   ```kotlin
   if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
       val pm = getSystemService(POWER_SERVICE) as PowerManager
       if (!pm.isIgnoringBatteryOptimizations(packageName)) {
           val intent = Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS)
           intent.data = Uri.parse("package:$packageName")
           startActivity(intent)
       }
   }
   ```

3. For Chinese phones (Xiaomi, Huawei, etc.), guide users to add app to "Protected Apps"

### "POST\_NOTIFICATIONS permission denied"

**Cause:** User denied permission on Android 13+.

**Solutions:**

1. Re-request with explanation:
   ```kotlin
   if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
       // Show dialog explaining why
       showRationaleDialog()
   } else {
       // Open app settings
       val intent = Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS)
       intent.putExtra(Settings.EXTRA_APP_PACKAGE, packageName)
       startActivity(intent)
   }
   ```

***

## Performance Issues

### "App memory keeps growing"

**Causes:**

* Coroutine scopes not cancelled
* Flow collectors not cancelled
* Strong references in callbacks

**Solutions:**

1. Use lifecycle-aware coroutines:
   ```kotlin
   class MyActivity : AppCompatActivity() {
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
           
           lifecycleScope.launch {
               // Auto-cancelled on destroy
               sdk.events.collect { handleEvent(it) }
           }
       }
   }
   ```

2. Use `viewLifecycleOwner.lifecycleScope` in Fragments

3. Use `repeatOnLifecycle`:
   ```kotlin
   lifecycleScope.launch {
       repeatOnLifecycle(Lifecycle.State.STARTED) {
           sdk.events.collect { handleEvent(it) }
       }
   }
   ```

### "SDK uses too much battery"

**Causes:**

* Long-running calls without proper cleanup
* Background services running unnecessarily
* Wake locks held too long

**Solutions:**

1. End calls properly when user navigates away
2. Don't hold wake locks beyond call duration
3. Use foreground service only during active calls

### "App launches slowly"

**Causes:**

* SDK initialization blocking main thread
* Too many synchronous operations on launch

**Solutions:**

1. Initialize SDK off main thread:
   ```kotlin
   class MyApplication : Application() {
       override fun onCreate() {
           super.onCreate()
           
           CoroutineScope(Dispatchers.IO).launch {
               sdk = KasookooSDK(this@MyApplication)
               sdk.initialize(config)
           }
       }
   }
   ```

2. Defer SDK init until needed:
   ```kotlin
   // Initialize when user logs in or makes first call
   ```

***

## Debugging Tools

### Enable Verbose Logging

```kotlin
val config = KasookooConfig(
    publishableKey = "...",
    organizationId = "...",
    logging = LoggingConfig(
        level = LogLevel.DEBUG,  // VERBOSE, DEBUG, INFO, WARNING, ERROR
        includeNetworkLogs = true,
        includeStateChanges = true
    )
)
```

### Inspect Events in Real Time

```kotlin
lifecycleScope.launch {
    sdk.events.collect { event ->
        Log.d("SDK", "📨 ${event.name} - ${event.data}")
    }
}
```

### Network Debugging with Charles/Proxyman

1. Install Charles Proxy on Mac/PC
2. Configure Android device to use Charles as proxy:
   * WiFi settings → Modify network → Proxy → Manual
   * Hostname: Your PC IP
   * Port: 8888
3. Install Charles CA certificate on device:
   * Browse to `chls.pro/ssl` from device
   * Install certificate
4. Configure network security config in Android app:
   ```xml
   <!-- res/xml/network_security_config.xml -->
   <network-security-config>
       <debug-overrides>
           <trust-anchors>
               <certificates src="user" />
           </trust-anchors>
       </debug-overrides>
   </network-security-config>
   ```

### LiveKit Debugging

Enable LiveKit verbose logs:

```kotlin
import io.livekit.android.LiveKit
import io.livekit.android.LogLevel

LiveKit.setLogLevel(LogLevel.DEBUG)
```

### Logcat Filtering

Filter Logcat for SDK logs:

```bash
adb logcat -s "KasookooSDK:V" "FCM:V" "Call:V"
```

### Crash Reports

Set up crash reporting (Firebase Crashlytics recommended):

```kotlin
dependencies {
    implementation("com.google.firebase:firebase-crashlytics-ktx")
}
```

***

## Getting Help

If you can't resolve an issue:

### Information to Include

When reporting issues, please provide:

1. **SDK version** (e.g., `1.0.0`)
2. **Android version** (e.g., Android 14, API 34)
3. **Device model** (e.g., `Samsung Galaxy S24`)
4. **Android Studio version** (e.g., `Iguana 2023.2.1`)
5. **Kotlin version** (e.g., `2.0.0`)
6. **Gradle version** (e.g., `8.4`)
7. **Steps to reproduce**
8. **Expected behavior** vs **actual behavior**
9. **Logcat output** (with sensitive data redacted)
10. **Configuration code** (with publishable key redacted)

### Where to Get Help

* 📧 <support@kasookoo.ai> — Direct support
* 💬 [Discord Community](https://discord.gg/kasookoo) — Community help
* 🐛 [GitHub Issues](https://github.com/kasookoo/android-sdk/issues) — Bug reports
* 📖 [Documentation](https://docs.kasookoo.ai) — Searchable docs
* 🚨 [status.kasookoo.ai](https://status.kasookoo.ai) — Service status

### Enterprise Support

Enterprise customers have access to:

* Dedicated Slack channel
* Priority response (4-hour SLA)
* Direct engineering escalation
* Video call support

Contact <sales@kasookoo.ai> to upgrade.