Troubleshooting Guide

Common issues and their solutions when working with LiteP2P.

Connection Issues

App can't connect to network

Symptom	ConnectionResult.Error returned from connect()
Possible Causes	No internet connection Invalid App ID Firewall blocking connections
Solutions	Check internet connectivity Verify App ID is correct Ensure ports 443, 8443 are open Check INTERNET permission in manifest

Connections drop when app goes to background

Symptom	Connections work in foreground but disconnect when backgrounded
Cause	Android background restrictions
Solution	Use Foreground Service for active operations Request battery optimization exemption Implement push notifications for wake-up

// Check if battery optimization is the issue
if (!LiteP2P.isBatteryOptimizationDisabled(context)) {
    LiteP2P.requestBatteryOptimizationExemption(context)
}

Works on Pixel, fails on Xiaomi/Samsung

Symptom	App works on stock Android but fails on OEM devices
Cause	OEM-specific battery optimization
Solution	Guide users to OEM-specific settings Use LiteP2P.showOEMConfigurationGuide() See OEM Behavior guide

Message Issues

Messages not delivered

Symptom	SendResult.Error or messages never received
Possible Causes	Peer not in READY state Peer disconnected Message too large
Solutions	Check peer state before sending Enable auto-retry in config Use file transfer API for large data

// Check peer state before sending
val peer = LiteP2P.getInstance().getPeer(peerId)
if (peer?.state == PeerState.READY) {
    peer.send(data)
} else {
    // Queue for later
    messageQueue.add(MessageQueueItem(peerId, data))
}

Push notifications not waking app

Symptom	Push notifications sent but app doesn't wake
Possible Causes	FCM token not registered Wrong message priority OEM blocking notifications
Solutions	Verify FCM token registration Use high-priority messages Check OEM notification settings

File Transfer Issues

Transfers fail midway

Symptom	File transfers start but fail before completion
Possible Causes	No foreground service Network change during transfer Insufficient storage
Solutions	Use Foreground Service for transfers Enable resume support Check available storage before starting

// Enable resume for reliable transfers
val options = FileTransferOptions.Builder()
    .setResumeEnabled(true)
    .setMaxRetries(3)
    .build()

val transfer = p2p.sendFile(peerId, file, options)

Debugging Tips

Enable Debug Logging

val config = PeerConfig.Builder()
    .setAppId("your-app-id")
    .setLogLevel(LogLevel.DEBUG)  // Enable verbose logging
    .build()

LiteP2P.initialize(context, config)

Validation Check

// Run integration validation
val validation = LiteP2P.validateIntegration(context)
validation.issues.forEach { issue ->
    Log.w("LiteP2P", "${issue.severity}: ${issue.description}")
    Log.w("LiteP2P", "Fix: ${issue.solution}")
}

Connection Diagnostics

// Get detailed connection info
val diagnostics = LiteP2P.getInstance().getDiagnostics()
Log.d("LiteP2P", "Connection state: ${diagnostics.connectionState}")
Log.d("LiteP2P", "Active peers: ${diagnostics.activePeerCount}")
Log.d("LiteP2P", "Push token: ${diagnostics.pushTokenRegistered}")
Log.d("LiteP2P", "Battery optimization: ${diagnostics.batteryOptimizationDisabled}")

Common Error Messages

Error	Meaning	Solution
NOT_INITIALIZED	LiteP2P.initialize() not called	Call initialize() in Application.onCreate()
INVALID_APP_ID	App ID not recognized	Check App ID spelling
PEER_NOT_FOUND	Target peer not in network	Verify peer ID, check peer is online
PEER_NOT_READY	Peer connection not established	Wait for READY state
NETWORK_ERROR	Network request failed	Check connectivity, retry
HANDSHAKE_FAILED	Encryption handshake failed	Check SDK version compatibility

Getting Help

If you're still having issues:

1. Check the docs – Most issues are covered in the documentation
2. Search GitHub Issues – Your issue may already be reported
3. Ask on Discord – Get help from the community
4. File a bug report – Include debug logs and device info