Troubleshooting

This guide covers common issues you may encounter when using Shield for iOS and how to resolve them.

Build Errors

Shield command not found

If you see shield-ios: command not found, the CLI tool is not in your PATH. Verify the installation:

pip show shield-ios

pip show shield-ios

If installed in a virtual environment, make sure the environment is activated. If using a CI system, ensure the pip installation step runs before the Shield step.

License validation failed

If the build fails with a license error, verify that your project token is correct in the configuration file and that your build machine has internet access. If you need to build without internet, use offline mode.

Python version error

Shield requires Python 3.8 or later. Check your Python version:

python3 --version

python3 --version

Code Signing Issues

Invalid signature after protection

Shield modifies the Mach-O binary, which invalidates the existing code signature. You must re-sign the application after protection. If using Xcode integration, ensure the Shield build phase runs before the code signing phase.

Provisioning profile mismatch

If you encounter provisioning profile errors after protection, verify that your code signing configuration matches the protected binary. The bundle identifier and entitlements are not modified by Shield.

Runtime Issues

Application crashes at launch

If the protected application crashes immediately, check whether you need to add exclusions for symbols that must retain their original names. Common causes include Interface Builder outlets referencing renamed classes, Codable types with renamed properties, and third-party SDKs that reference your classes by name.

Anti-debug triggers during development

Anti-Debug will trigger when Xcode's debugger is attached. Use Build Profiles to skip runtime protections during development, or enable skip_debug in your build integration configuration.

Jailbreak detection false positives

If Anti-Jailbreak triggers on non-jailbroken devices, try lowering the sensitivity level. The default sensitivity (1) is appropriate for most applications:

{
  "anti_jailbreak": {
    "enabled": true,
    "sensitivity": 0
  }
}

{
  "anti_jailbreak": {
    "enabled": true,
    "sensitivity": 0
  }
}

Performance Issues

Build takes too long

Protection time depends on the number and intensity of protections enabled and the size of your binary. For faster builds during development, use Build Profiles with lighter protections or skip protection entirely for Debug builds.

Binary size increased significantly

Some protections increase binary size, particularly Dead Code Injection at the heavy level. If binary size is a concern, use lighter intensity levels or disable the most size-impactful protections.

Logs

Shield generates detailed logs during protection. Check the log output for diagnostic information:

shield-ios protect MyApp.ipa -c shield-ios.json --verbose

shield-ios protect MyApp.ipa -c shield-ios.json --verbose

You can also configure logging in your configuration file:

{
  "logging": {
    "level": "debug",
    "file": "shield.log",
    "console": true
  }
}

{
  "logging": {
    "level": "debug",
    "file": "shield.log",
    "console": true
  }
}

Related

• Configuration Reference - Full configuration options
• Exclusions - Configure exclusion patterns
• Best Practices - Recommended protection strategies