Flutter request fails with SocketException: Failed host lookup
SocketException: Failed host lookup: 'api.example.com' (OS Error: No address associated with hostname, errno = 7)Short answer
Failed host lookup means the app could not turn the host name into an IP address, so no request was sent. On Android check the INTERNET permission first. On macOS add the network client entitlement. If both are fine, the device or emulator has no working DNS for that name.
Fix it fast
1Find out which cause you have
Check the first cause on Android: the manifest must declare INTERNET. Then open the same URL in the browser on the device or emulator, outside your app, to see whether the device can resolve the name at all.
grep -n 'INTERNET' android/app/src/main/AndroidManifest.xml2Match what you see, then jump to its fix
- 1
Every request fails with host lookup, on any network, in a release or a fresh buildThe Android manifest does not declare the INTERNET permissionFix - 2
Fails only in the macOS build of the same appThe macOS app is sandboxed without the network client entitlementFix - 3
The name works in your browser on the computer, but not on the emulator, often on a VPN or office networkThe emulator's DNS cannot resolve the nameFix - 4
Fails for a local dev name such as myapp.test or an entry from /etc/hostsThe name only exists on your computerFix
- 1
What does the error look like?
SocketException: Failed host lookup: 'api.example.com' (OS Error: No address associated with hostname, errno = 7)ClientException with SocketException: Failed host lookupnodename nor servname provided, or not known
Cause 1 of 4
The Android manifest does not declare the INTERNET permission
1Check
Network access needs the INTERNET permission in the manifest. It is a normal permission, granted at install time, so there is no prompt and no runtime request.
grep -n 'INTERNET' android/app/src/main/AndroidManifest.xml2Fix
Add the permission inside the manifest element, above the application element.
<uses-permission android:name="android.permission.INTERNET" />3Verify
Rebuild and install, then repeat the request.
flutter clean
flutter run --releaseConfirmed by developer.android.com
Cause 2 of 4
The macOS app is sandboxed without the network client entitlement
1Check
Sandboxed macOS apps need the outgoing network entitlement in both entitlement files.
grep -n 'network.client' macos/Runner/*.entitlements2Fix
Add the key to DebugProfile.entitlements and Release.entitlements.
<key>com.apple.security.network.client</key>
<true/>3Verify
Stop the app and run it again on macOS.
flutter run -d macosConfirmed by docs.flutter.dev
Cause 3 of 4
The emulator's DNS cannot resolve the name
1Check
At start-up the emulator copies the DNS servers your computer uses. A VPN or a changed network leaves it with servers that do not answer.
adb devices2Fix
Restart the emulator from the command line with DNS servers you name, or restart it after the network settles.
emulator @Pixel_8 -dns-server 8.8.8.8,8.8.4.43Verify
The page for the name opens in the emulator browser and the app request succeeds.
flutter runConfirmed by developer.android.com
Cause 4 of 4
The name only exists on your computer
1Check
The emulator ignores your computer's hosts file. And inside it, 127.0.0.1 is the emulator itself, not your computer.
grep myapp /etc/hosts2Fix
Reach a server on your computer with the alias 10.0.2.2, or use a name that public or your own DNS can resolve.
final uri = Uri.parse('http://10.0.2.2:3000/api/items');3Verify
The request leaves the emulator and gets a response.
flutter runConfirmed by developer.android.com
How do I stop it coming back?
- Add the INTERNET permission and the macOS entitlement when you first add an HTTP package.
- Keep API base URLs in one config value so a typo cannot hide in a screen file.
- Catch SocketException and show a retry message instead of a raw error.
- Test on a real device and on the emulator before a release.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
Flutter deep link works while the app is open but not from a closed app
From a fully closed app the link opens only the home screen
On a cold start Flutter does not push the link; it starts the app with an initial route that holds the link path.
3 causes, each with a fixMobile apps
Flutter Image.network shows nothing or throws when the image fails
EXCEPTION: resolving an image codec
Image.network throws an exception that goes to FlutterError.onError when a download or decode fails, so a 404 leaves a red screen or an empty box.
3 causes, each with a fixMobile apps
Flutter cannot open a file: OS Error No such file or directory
FileSystemException: Cannot open file, path = '...' (OS Error: No such file or directory, errno = 2)
Errno 2 means the exact path you gave does not exist on the device.
3 causes, each with a fixMobile apps
Flutter file write fails with Permission denied (errno = 13)
OS Error: Permission denied, errno = 13
Errno 13 means the operating system refused the file operation.
2 causes, each with a fixMobile apps
Flutter says Unable to load asset for an image or file that exists
The asset does not exist or has empty data.
Flutter only bundles files that pubspec.yaml lists.
4 causes, each with a fixMobile 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