Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Flutter app cannot reach a local Django or Node backend: Connection refused, errno = 111

ErrorSocketException: Connection refused (OS Error: Connection refused, errno = 111)

Short answer

Connection refused means the app reached a machine, but nothing accepted the connection on that address and port. On an Android emulator, localhost is the emulator itself, so use 10.0.2.2 for your computer. On a real phone use your computer's LAN address, and start the server on 0.0.0.0, not only on 127.0.0.1.

  • Applies to Flutter 3.3x stable, Android Emulator 36.x, Django 5.2 runserver, package:http
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the address in the exception, and test that same address from where the app runs. If the app runs on an emulator or phone, a plain curl on your computer proves nothing about its address, so first see which kind of device you are on.

    flutter devices
  2. 2Match what you see, then jump to its fix

    1. 1address = localhost or 127.0.0.1, only on an emulator, while the browser on your computer worksThe app uses localhost or 127.0.0.1 inside the Android EmulatorFix
    2. 2Phone and computer are on the same Wi-Fi, the app uses your computer's address, and the connection is still refusedA physical phone is pointed at the computer, but the server listens only on 127.0.0.1Fix
    3. 3The server listens on 0.0.0.0 but only your own computer can open itA firewall or a different network blocks the connection to your computerFix

What does the error look like?

  • SocketException: Connection refused (OS Error: Connection refused, errno = 111)
  • ClientException with SocketException: Connection refused

Cause 1 of 3

The app uses localhost or 127.0.0.1 inside the Android Emulator

1Check

Android's emulator docs say 127.0.0.1 inside the emulator is the emulated device's own loopback interface. The alias 10.0.2.2 reaches the loopback of your development machine.

grep -rn -E "localhost|127\.0\.0\.1" lib/

2Fix

Use 10.0.2.2 as the host on the emulator, with the port your server listens on. Keep the host in one config value so a release build can use the real domain.

import 'dart:io' show Platform;

final apiHost = Platform.isAndroid ? '10.0.2.2' : 'localhost';
final baseUrl = Uri.parse('http://$apiHost:8000/api/');

3Verify

The request now returns a response instead of errno = 111.

flutter run -d emulator-5554

Confirmed by developer.android.com

Did this fix it?

Cause 2 of 3

A physical phone is pointed at the computer, but the server listens only on 127.0.0.1

1Check

Django's runserver defaults to port 8000 on 127.0.0.1, an address other machines cannot reach, as its documentation states.

lsof -nP -iTCP:8000 -sTCP:LISTEN

2Fix

Start the dev server on all interfaces, then use your computer's LAN IP address in the app, such as the address shown in your network settings.

python manage.py runserver 0.0.0.0:8000

3Verify

Open http://<computer-lan-ip>:8000/ in the phone's browser first; if that loads, the app can reach it too.

curl -I http://<computer-lan-ip>:8000/

Confirmed by docs.djangoproject.com

Did this fix it?

Cause 3 of 3

A firewall or a different network blocks the connection to your computer

1Check

Android's docs list firewall programs on your machine, and a physical firewall or router between the devices, as things that can block communication with the emulated device.

curl -I http://<computer-lan-ip>:8000/

2Fix

Allow incoming connections to that port in the computer's firewall for the private network, or move the phone to the same network as the computer.

# in your operating system's firewall settings,
# allow incoming connections to port 8000 on the private network

3Verify

The phone's browser loads the server's page.

curl -I http://<computer-lan-ip>:8000/

Confirmed by developer.android.com

Did this fix it?

How do I stop it coming back?

  • Keep the API base URL in one place and switch it per build flavor, so a debug host never reaches a release.
  • Use 10.0.2.2 for the Android Emulator and the computer's LAN address for phones.
  • Test a new server address in the device browser before debugging Dart code.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Google Play says the app does not support 16 KB memory pages

check_elf_alignment.sh reports UNALIGNED for a library under lib/arm64-v8a

Google Play requires apps that target Android 15 or higher and ship native .so libraries to run on devices with 16 KB memory pages; from 1 February 2027 it will block updates that do not.

5 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.