A Flutter macOS app cannot reach the network: Operation not permitted
SocketException: Connection failed (OS Error: Operation not permitted, errno = 1), address = example.com, port = 443Short answer
A sandboxed macOS app is blocked from the network unless it holds an entitlement. Add com.apple.security.network.client set to true in macos/Runner/DebugProfile.entitlements and Release.entitlements, then rebuild. Apps that also listen for incoming connections need com.apple.security.network.server in the release file, because only debug and profile get it by default.
Fix it fast
1Find out which cause you have
Check which network entitlements both macOS entitlement files already hold.
grep -n "network" macos/Runner/*.entitlements2Match what you see, then jump to its fix
- 1
Every request fails with errno = 1 on macOS while the same code works on Android, iOS and webThe outgoing network entitlement is missingFix - 2
It works in debug or profile mode, but the release build cannot listen or accept connectionsThe app accepts incoming connections, and only the release build failsFix
- 1
What does the error look like?
SocketException: Connection failed (OS Error: Operation not permitted, errno = 1), address = example.com, port = 443
Cause 1 of 2
The outgoing network entitlement is missing
1Check
Open both entitlement files in macos/Runner. Without com.apple.security.network.client set to true, App Sandbox refuses outgoing requests.
cat macos/Runner/DebugProfile.entitlements
cat macos/Runner/Release.entitlements2Fix
Add the key to both files, with the same change in each, then stop the app and run it again.
<key>com.apple.security.network.client</key>
<true/>3Verify
Run the app again and repeat the request that failed.
flutter run -d macosConfirmed by docs.flutter.dev
Cause 2 of 2
The app accepts incoming connections, and only the release build fails
1Check
The incoming-connection entitlement com.apple.security.network.server is on by default only in the debug and profile entitlements. The release file does not have it.
grep -n "network.server" macos/Runner/*.entitlements2Fix
If your app opens a server socket, add the key to Release.entitlements too. Do not remove the existing entries from DebugProfile.entitlements.
<key>com.apple.security.network.server</key>
<true/>3Verify
Build and run a release build and test the incoming connection.
flutter run --release -d macosConfirmed by docs.flutter.dev
How do I stop it coming back?
- Add com.apple.security.network.client to both entitlement files in the same commit as the first HTTP call.
- Test a release build on macOS before shipping, not only debug runs.
- Keep both entitlement files in review whenever a plugin asks for new capabilities.
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.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
Related fixes
Mobile apps
Apple rejected the app under Guideline 4.3, Design: Spam
Guideline 4.3(b) - Design - Spam
Guideline 4.3 is Apple's duplicate rule.
5 causes, each with a fixMobile apps
pod install cannot pick a version of a pod that satisfies every requirement
Specs satisfying the `FirebaseAuth (~> 11.0)` dependency were found, but they required a higher minimum deployment target.
CocoaPods tried every version of the named pod and none fit all requirements.
4 causes, each with a fixMobile apps
flutter run says: Could not run Runner.app, try Xcode Product > Run
Try launching Xcode and selecting "Product > Run" to fix the problem:
Flutter prints this when installing or launching the built app on the iPhone fails, and it hides the real reason.
4 causes, each with a fixMobile apps
flutter doctor says CocoaPods is installed but not working
You appear to have CocoaPods installed but it is not working.
Flutter runs pod --version and treats a failed or unreadable result as a broken install.
3 causes, each with a fixMobile apps
flutter run on iOS or macOS stops with Error running pod install
Warning: CocoaPods not installed. Skipping pod install.
Flutter only reports that pod install failed; the reason is in the lines just above it.
5 causes, each with a fixMobile apps
FirebaseMessaging.getAPNSToken() returns null on iOS
FirebaseMessaging.instance.getAPNSToken() returns null
getAPNSToken() gives null when iOS has not handed the app an APNs token yet or never will.
4 causes, each with a fix