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. Exclude the package:

   Kotlin

   Copy

   excludePackages("com.example.receivers")

   excludePackages("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:

excludePackages("com.example.models")

excludePackages("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('BYTEHIDE_PROJECT_TOKEN')
}

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

Check that the environment variable is defined:

echo $BYTEHIDE_PROJECT_TOKEN

echo $BYTEHIDE_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. Verify the URL https://shield.microservice.bytehide.com is reachable from your build machine

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:

excludePackages("kotlinx")

excludePackages("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 }
    }
}

Build Errors (Advanced)

IllegalAccessError After Repackaging

Symptom: IllegalAccessError when accessing package-private classes or members after enabling repackageClasses.

Cause: A package-private class/member is accessed from another package after flattening.

Solution: This should be handled automatically by access widening. If not, exclude the package from name obfuscation:

excludePackages("com.example.internal:NameObfuscation")

excludePackages("com.example.internal:NameObfuscation")

VerifyError or AbstractMethodError

Symptom: VerifyError or AbstractMethodError at runtime.

Cause: Control flow obfuscation broke bytecode invariants in the affected class.

Solution: Exclude the problematic class from ControlFlow:

excludePackages("com.example.problematic:ControlFlowMatrix")

excludePackages("com.example.problematic:ControlFlowMatrix")

Build Hangs or OOM

Cause: Too many classes being processed without exclusions.

Solution: Increase heap size and exclude large library packages:

// In gradle.properties
// org.gradle.jvmargs=-Xmx4g

// In shield config
excludePackages("com.thirdparty.library")

// In gradle.properties
// org.gradle.jvmargs=-Xmx4g

// In shield config
excludePackages("com.thirdparty.library")

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