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

   Permissive mode lets unregistered domains through without pinning and emits no validation events. It is set in the app’s configuration, so release builds must use strict.

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, early warning)
Upload New Cert: 2026-12-17 (14 days before, publish deadline)

The alert gives you time to prepare. The pin must be published at least 7-14 days before expiry so both pins overlap. See Planning Certificate Updates.

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 {
            let config = TrustPinConfiguration(
                organizationId: "your-org-id",
                projectId: "your-project-id",
                publicKey: "your-base64-public-key",
                mode: .strict
            )
            try await TrustPin.setup(config)
        }
        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:6.4.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, '15.0'  # Minimum iOS 15

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
 
  const config = TrustPinConfiguration(
    organizationId: 'your-org-id',
    projectId: 'your-project-id',
    publicKey: 'your-base64-public-key',
    mode: TrustPinMode.strict,
  );
  await TrustPin.shared.setup(config);
 
  runApp(const 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

Configuration URL Rejected After Upgrading to 6.4.0

Problem: A custom configurationURL that worked on 6.3.x now fails at setup

Symptoms:

• Setup fails with INVALID_PROJECT_CONFIG immediately after upgrading to 6.4.0
• The URL points at localhost, 127.0.0.1, a 192.168.x.x address, or the Android emulator alias 10.0.2.2
• Builds using the default hosted configuration are unaffected

Cause: From 6.4.0 the signed configuration may only be fetched over HTTPS from a public host. Loopback and private addresses are rejected at setup. They are not fetched and do not fall back to the TrustPin CDN (the CDN fallback applies only when a valid custom URL cannot be fetched at runtime).

Solutions:

1. Leave configurationURL unset in development and use the hosted configuration. This is the right answer for almost every app
2. Serve the signed payload from a public HTTPS host if you genuinely self-host it. trustpin-cli projects jws writes the published payload to a file you can upload
3. Do not confuse this with pinning your own API. The restriction applies only to where the configuration is loaded from. A local or private API host is still pinned normally, subject to the mode you configured

See the per-platform notes: Swift, Kotlin, Flutter, React Native.

Testing with Local/Development Server

Problem: Need to test with local server without SSL

Solutions:

1. Use permissive mode:

   mode: .permissive  // Allows unregistered domains

   Unregistered domains are not pinned and emit no validation events in permissive mode. Release builds must use strict.

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.shared.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
  • React Native SDK
• 💬 Dashboard: app.trustpin.cloud 

Additional Resources

• Setup Guide
• Deployment Guide
• Certificate Pinning Explained