Troubleshooting

This page covers the most common issues encountered when using Shield and how to resolve them.

Runtime Crashes

ClassNotFoundException After Obfuscation

Symptom: ClassNotFoundException or ClassCastException at runtime.

Cause: A class is looked up by its original name (via reflection, XML configuration, or manifest) but has been renamed by name obfuscation.

Solutions:

1. Add @Keep to the affected class:

   Java

   Copy

   @Keep
   public class MyBroadcastReceiver extends BroadcastReceiver { }

   @Keep
   public class MyBroadcastReceiver extends BroadcastReceiver { }

2. Add the package to excludedPackages:

   Groovy

   Copy

   excludedPackages = ['com.example.receivers']

   excludedPackages = ['com.example.receivers']

3. If R8 is also renaming, disable Shield's name obfuscation:

   Groovy

   Copy

   protections { nameObfuscation = false }

   protections { nameObfuscation = false }

NoSuchMethodError After Obfuscation

Symptom: NoSuchMethodError at runtime when calling methods that exist in the source.

Cause: A method was renamed by name obfuscation but is called by name from another context (reflection, JNI, or serialization framework).

Solution: Apply @DoNotObfuscate to the class or method:

@DoNotObfuscate
public class NativeInterface {
    public native void processData(byte[] input);
}

@DoNotObfuscate
public class NativeInterface {
    public native void processData(byte[] input);
}

Gson/Moshi Serialization Failures

Symptom: JSON serialization/deserialization produces empty objects or throws exceptions.

Cause: Gson and Moshi map JSON keys to field names. If fields are renamed, the mapping breaks.

Solution: Use @Keep on model classes:

@Keep
data class User(
    val id: String,
    val name: String,
    val email: String
)

@Keep
data class User(
    val id: String,
    val name: String,
    val email: String
)

Or exclude the model package:

excludedPackages = ['com.example.models']

excludedPackages = ['com.example.models']

Build Errors

Authentication Error

Symptom: Build fails with a token validation error.

Causes:

• Missing or invalid project token
• Token not set as environment variable in CI/CD
• No internet connectivity during build

Solution: Verify the token is set correctly:

shield {
    projectToken = System.getenv('SHIELD_PROJECT_TOKEN')
}

shield {
    projectToken = System.getenv('SHIELD_PROJECT_TOKEN')
}

Check that the environment variable is defined:

echo $SHIELD_PROJECT_TOKEN

echo $SHIELD_PROJECT_TOKEN

Cloud Registration Failed

Symptom: RuntimeException: Cloud registration failed. Obfuscation cannot complete without cloud sync.

Cause: The build machine cannot reach https://shield.microservice.bytehide.com.

Solutions:

1. Check network connectivity and firewall rules
2. For local development, use offline mode:
   Bash

   Copy

   SHIELD_OFFLINE=true ./gradlew assembleRelease

   SHIELD_OFFLINE=true ./gradlew assembleRelease

Kotlin-Specific Issues

Kotlin Reflection Breaks

Symptom: KotlinReflectionInternalError or properties not found via ::class.memberProperties.

Cause: Kotlin stores property names in kotlin.Metadata annotations. Name obfuscation renames the bytecode fields but the metadata still references original names.

Solution: Apply @DoNotObfuscate to classes that use Kotlin reflection:

@DoNotObfuscate
data class Config(val host: String, val port: Int)

@DoNotObfuscate
data class Config(val host: String, val port: Int)

Coroutine Issues

Symptom: Coroutines behave unexpectedly or crash after obfuscation.

Solution: Exclude the kotlinx.coroutines package:

excludedPackages = ['kotlinx']

excludedPackages = ['kotlinx']

Anti-Debug Triggers in Development

Symptom: App crashes immediately when launched from Android Studio.

Cause: Anti-debug is enabled and detects Android Studio's debugger.

Solution: Disable anti-debug for debug builds:

shield {
    variant('debug') {
        protections { antiDebug = false }
    }
}

shield {
    variant('debug') {
        protections { antiDebug = false }
    }
}

Performance Issues

Symptom: Application is noticeably slower after enabling protections.

Cause: Control flow obfuscation adds overhead to frequently-called methods.

Solution: Exclude performance-critical methods:

@Exclude(protections = {"ControlFlowMatrix"})
public void onDraw(Canvas canvas) {
    // Rendering code
}

@Exclude(protections = {"ControlFlowMatrix"})
public void onDraw(Canvas canvas) {
    // Rendering code
}

Diagnostic Steps

When encountering issues:

1. Enable verbose mode — Set verbose = true to see what Shield processes
2. Disable protections one by one — Isolate which protection causes the issue
3. Check excluded packages — Ensure framework packages are excluded
4. Review annotations — Add @Keep or @Exclude to affected code
5. Compare with unprotected build — Build without Shield to confirm the issue is protection-related

Related

• Annotations — Excluding elements from protection
• Excluded Packages — Skipping packages
• Variant Configuration — Per-build-type settings