Troubleshooting

Common issues and solutions for TrustPin integration.

Setup & Configuration

Invalid Project Configuration

Error: INVALID_PROJECT_CONFIG

Symptoms:

• SDK setup fails immediately
• “Invalid credentials” message

Solutions:

1. Verify credentials in TrustPin Dashboard :
   • Organization ID is correct
   • Project ID matches your project
   • Public Key is base64-encoded
2. Check for whitespace or line breaks in credentials
3. Ensure you’re using the correct environment (dev/staging/prod)
4. Verify credentials aren’t expired or revoked

Example (iOS):

// **No:** Wrong - contains whitespace
publicKey: "LS0tLS1C RUdJTi..."
 
// **Yes:** Correct - no whitespace
publicKey: "LS0tLS1CRUdJTi..."

Configuration Fetch Failed

Error: ERROR_FETCHING_PINNING_INFO

Symptoms:

• Can’t fetch configuration from CDN
• Network timeout errors

Solutions:

1. Check internet connectivity:

   # Test CDN access
   curl https://cdn.trustpin.cloud/health

2. Verify firewall/proxy settings:

   • Allow HTTPS to cdn.trustpin.cloud
   • Ensure no SSL inspection is blocking requests

3. Check TrustPin service status:

   • Visit status.trustpin.cloud 

4. Retry with exponential backoff:

   // iOS - automatic retry built-in
   try await TrustPin.setup(...)  // Retries 3 times with backoff

Signature Validation Failed

Error: CONFIGURATION_VALIDATION_FAILED

Symptoms:

• Configuration downloaded but rejected
• JWS signature invalid

Solutions:

1. Verify public key is correct (copy from dashboard)
2. Ensure public key format is valid base64
3. Check for Man-in-the-Middle proxy interfering with CDN
4. Verify app hasn’t been modified (root/jailbreak detection)

Certificate Validation Issues

Pins Mismatch

Error: PINS_MISMATCH

Symptoms:

• All requests to a specific domain fail
• “Certificate doesn’t match pins” message

Solutions:

1. Verify domain is registered:

   • Check TrustPin Dashboard 
   • Ensure domain has active pins

2. Check certificate fingerprint:

   # Get server's certificate fingerprint
   openssl s_client -connect api.example.com:443 </dev/null 2>/dev/null | \
     openssl x509 -noout -fingerprint -sha256

3. Refresh configuration:

   • Wait up to 10 minutes for cache to expire
   • Or restart app to force refresh

4. Verify certificate hasn’t been rotated:

   • Upload new certificate to dashboard if rotated
   • Ensure both old and new pins are active during transition

Testing:

// Enable debug logging to see pin details
await TrustPin.set(logLevel: .debug)

Domain Not Registered

Error: DOMAIN_NOT_REGISTERED

Symptoms:

• Requests fail in strict mode
• Domain not configured message

Solutions:

1. Add domain to TrustPin project:

   • Go to dashboard → Add Domain
   • Upload certificate for the domain

2. Use permissive mode for testing:

   // Temporarily allow unregistered domains
   mode: .permissive  // Switch to .strict for production

3. Check domain name is exact:

   **No:** Wrong: "www.api.example.com"
   **Yes:** Correct: "api.example.com"

All Pins Expired

Error: ALL_PINS_EXPIRED

Symptoms:

• All requests fail
• “Pins expired” message

Solutions:

1. Upload new certificate to dashboard
2. Update pin expiration dates in project settings
3. Set up expiration alerts to prevent future issues

Prevention:

Certificate Expiration: 2026-12-31
Set TrustPin Alert: 2026-11-01 (60 days before)
Upload New Cert: 2026-11-15 (45 days before)

Platform-Specific Issues

iOS

App Transport Security (ATS) Blocks Requests

Symptoms:

• All network requests fail
• ATS error in console

Solutions: Add ATS exception in Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <false/>
    <key>NSExceptionDomains</key>
    <dict>
        <key>cdn.trustpin.cloud</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <false/>
            <key>NSExceptionMinimumTLSVersion</key>
            <string>TLSv1.2</string>
        </dict>
    </dict>
</dict>

SDK Not Initialized

Symptoms:

• Pinning doesn’t work
• No errors shown

Solutions:

// **Yes:** Initialize in AppDelegate
class AppDelegate: UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Task {
            try await TrustPin.setup(...)
        }
        return true
    }
}

CocoaPods Installation Issues

Symptoms:

• pod install fails
• Module not found errors

Solutions:

# Clean and reinstall
pod deintegrate
pod install
 
# Update CocoaPods
sudo gem install cocoapods
pod setup

Android

ProGuard/R8 Strips TrustPin Classes

Symptoms:

• Works in debug, fails in release
• ClassNotFoundException

Solutions: Add to proguard-rules.pro:

# TrustPin SDK
-keep class cloud.trustpin.** { *; }
-keepclassmembers class cloud.trustpin.** { *; }
-keep class cloud.trustpin.kotlin.sdk.TrustPinError { *; }
-keep class cloud.trustpin.kotlin.sdk.TrustPinError$* { *; }

Network Security Config Conflicts

Symptoms:

• Certificate pinning doesn’t work
• Network Security Config overrides TrustPin

Solutions: Remove conflicting Network Security Config or integrate it:

<!-- res/xml/network_security_config.xml -->
<network-security-config>
    <base-config cleartextTrafficPermitted="false">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
    <!-- Let TrustPin handle pinning via SDK -->
</network-security-config>

Application Class Not Registered

Symptoms:

• TrustPin never initializes
• No setup errors

Solutions: Register in AndroidManifest.xml:

<application
    android:name=".MyApplication"  <!-- Add this -->
    ...>
</application>

OkHttp Version Incompatibility

Symptoms:

• Interceptor not working
• Method not found errors

Solutions:

// Ensure compatible OkHttp version
dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.12.0")  // 4.x required
    implementation("cloud.trustpin:kotlin-sdk:2.0.0")
}

Flutter

Hot Reload Doesn’t Apply Changes

Symptoms:

• Configuration changes not reflected
• Old pins still active

Solutions:

# Use hot restart (not hot reload)
flutter run
 
# Or force restart
r  # Press 'r' in console for restart

Platform Version Too Old

Symptoms:

• Compilation errors
• Platform not supported

Solutions: Update minimum versions in platform configs:

iOS (ios/Podfile):

platform :ios, '13.0'  # Minimum iOS 13

Android (android/app/build.gradle):

minSdkVersion 25  // Minimum API 25

WidgetsFlutterBinding Not Initialized

Symptoms:

• TrustPin.setup() fails
• Binding error

Solutions:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();  // Add this first
 
  await TrustPin.setup(...);
 
  runApp(MyApp());
}

Performance Issues

Slow App Startup

Symptoms:

• App launch delayed
• Setup takes >1 second

Solutions:

1. Initialize in background:

   // iOS
   Task(priority: .background) {
       try await TrustPin.setup(...)
   }

2. Don’t block UI thread:

   // Android
   lifecycleScope.launch(Dispatchers.IO) {
       TrustPin.setup(...)
   }

3. Use local cache:

   • TrustPin caches configuration for 10 minutes
   • Subsequent launches use cached data

High Memory Usage

Symptoms:

• App uses more memory than expected
• Memory warnings on iOS

Solutions:

• TrustPin SDK footprint: ~500 KB - 1 MB (normal)
• Clear cache if needed:

  // Restart app to clear cache

• Check for memory leaks in your implementation

Network Requests Slow

Symptoms:

• API calls take longer than expected
• Certificate validation adds latency

Solutions:

• TrustPin overhead: ~1-5ms per request (minimal)
• Check network connectivity
• Profile with logging:

  await TrustPin.set(logLevel: .debug)
  // Check logs for validation timing

Development & Testing

Testing with Local/Development Server

Problem: Need to test with local server without SSL

Solutions:

1. Use permissive mode:

   mode: .permissive  // Allows unregistered domains

2. Add localhost exception (temporary):

   #if DEBUG
   mode: .permissive
   #else
   mode: .strict
   #endif

Corporate Proxy/SSL Inspection

Problem: Corporate proxy intercepts SSL traffic

Symptoms:

• All HTTPS requests fail with PINS_MISMATCH
• Works outside corporate network

Solutions: Certificate pinning intentionally blocks SSL inspection (by design).

Options:

1. Use permissive mode for development:

   #if DEBUG
   mode: .permissive
   #endif

2. Add corporate CA to pins (enterprise apps only):

   • Not recommended for public apps
   • Reduces security benefits

3. Configure VPN bypass for TrustPin CDN:

   Exclude: cdn.trustpin.cloud from proxy

Simulator vs Physical Device

Symptoms:

• Works in simulator, fails on device
• Or vice versa

Solutions:

1. Always test on physical devices before release
2. Check for jailbreak detection interfering
3. Verify network configuration differs between sim/device

Common Error Codes

Debugging Tips

Enable Debug Logging

iOS:

await TrustPin.set(logLevel: .debug)

Android:

TrustPin.setLogLevel(TrustPinLogLevel.DEBUG)

Flutter:

await TrustPin.setLogLevel(TrustPinLogLevel.debug);

Check Configuration Endpoint

Test if CDN is accessible:

# Replace with your org and project IDs
curl https://cdn.trustpin.cloud/v1/configurations/org-123/proj-456

Verify Certificate Fingerprint

# Get server's certificate SHA-256 fingerprint
echo | openssl s_client -connect api.example.com:443 2>/dev/null | \
  openssl x509 -noout -fingerprint -sha256

Test with Different Networks

• Try on WiFi vs cellular
• Test from different geographic locations
• Check corporate network vs home network

Still Having Issues?

Before Contacting Support

Collect this information:

1. Platform (iOS/Android/Flutter)
2. SDK version
3. Error code and full error message
4. Logs with debug logging enabled
5. Steps to reproduce
6. Network environment (corporate/home/cellular)

Get Help

• 📧 Email: support@trustpin.cloud
• 🌐 Status: status.trustpin.cloud 
• 📚 Documentation:
  • iOS SDK
  • Android SDK
  • Flutter SDK
• 💬 Dashboard: app.trustpin.cloud 

Additional Resources

• Setup Guide
• Deployment Guide
• Certificate Pinning Explained