emulator connection refused errors

[Pixell-droid]

How do I connect the Android app to the backend API? I keep getting connection refused errors.

[flow-pie]

This is usually caused by the Android emulator not being able to reach localhost. Here's how to fix it:

The Issue

When running in the Android emulator, localhost or 127.0.0.1 refers to the emulator itself, not your development machine.

Solution

For Android Emulator

Use 10.0.2.2 instead of localhost. Update your Retrofit base URL:

// In your network configuration
object ApiClient {
    private const val BASE_URL = "http://10.0.2.2:8080/api/"
    
    val retrofit: Retrofit = Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create())
        .client(okHttpClient)
        .build()
}

10.0.2.2 is the special alias the Android emulator uses to reach your host machine's localhost.

For Physical Device

If testing on a real device over USB:

# Forward the port via ADB
adb reverse tcp:8080 tcp:8080

Then you can use http://localhost:8080/api/ in your app.

For Docker

If your backend runs in Docker, make sure the port is exposed:

docker-compose up -d
# API is at http://localhost:8080/api from your machine
# Use http://10.0.2.2:8080/api from the emulator

Check the AndroidManifest.xml

Ensure you have internet permission:

<uses-permission android:name="android.permission.INTERNET" />

And if using HTTP (not HTTPS), add android:usesCleartextTraffic="true" to your <application> tag, or use a network security config.
See docs/ANDROID.md for the full Android app setup.