Troubleshooting

Solutions for the most common issues when integrating Snapbug.

Chrome Extension pairing

"Failed to reach relay" — check the relay host URL in the extension popup; if you run a local relay, make sure it is up and reachable.

Room code shown but the device never connects

• Make sure the app really initialized the SDK (Snapbug.start(this) on Android).
• Check that the device has internet access to reach the relay.
• Room codes expire after about 5 minutes — press Connect again to get a fresh code.

Inspector tab is blank or slow to load — the Compose Wasm UI requires Chrome 116+; the first load initializes a Wasm bundle of roughly 14 MB and can take a few seconds.

Local service not detected — run snapbug status to confirm the service is running, and check that nothing blocks port 9090. The extension probes http://localhost:9090/api/status on startup.

Network Security Configuration

This section only applies to the direct localhost connection — the default Chrome Extension flow over WebRTC does not need it.

Starting with Android 9 (API 28), cleartext (non-HTTPS) traffic is blocked by default. Since the Snapbug SDK communicates with the local service over localhost using cleartext HTTP and WebSocket, you need to explicitly allow it.

1. Create a Network Security Config file

Create res/xml/network_security_config.xml in your app module:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="false">localhost</domain>
        <domain includeSubdomains="false">127.0.0.1</domain>
    </domain-config>
</network-security-config>

2. Reference it in AndroidManifest.xml

<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >
</application>

Debug-only configuration

If you want to restrict this to debug builds only, create separate manifest files:

src/debug/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:networkSecurityConfig="@xml/network_security_config" />
</manifest>

Place the network_security_config.xml file in src/debug/res/xml/ instead of src/main/res/xml/.

Device Not Detected (direct localhost connection)

If the local service or desktop app does not detect your device:

1. Check ADB -- Run adb devices and verify your device is listed.
2. Check port forwarding -- Run adb forward tcp:9023 tcp:9023 and adb forward tcp:9024 tcp:9024.
3. Restart ADB -- Run adb kill-server && adb start-server.
4. Check the app is running -- The SDK only connects when the app with Snapbug initialized is in the foreground.

SDK Not Initializing

• Verify you called Snapbug.start(this) in your launcher Activity's onCreate().
• Check that you are using debugImplementation for the SDK and releaseImplementation for the no-op artifact — with releaseImplementation("ai.snapbug:snapbug-no-op") in a release build the SDK intentionally does nothing.

Emulator Connection Issues

Emulators should connect automatically since they share localhost with the host machine. If not:

• Make sure the local service (or desktop app) is running before launching the emulator app.
• Try restarting the service: snapbug stop && snapbug serve.
• Check that no other process is using ports 9023 or 9024.

Wi-Fi Connection Not Working

When connecting over Wi-Fi:

• Both the device and the computer must be on the same network.
• Some corporate or guest networks block device-to-device communication. Try a different network or use USB instead.
• Verify the computer's local IP address is correct (use ifconfig on macOS/Linux or ipconfig on Windows).

ProGuard / R8 Issues

If you encounter issues with minified builds, add this to your ProGuard rules:

-keep class io.snapbug.sdk.** { *; }