Maaz Zindani

Loading the index…

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

A Flutter macOS app cannot reach the network: Operation not permitted

ErrorSocketException: Connection failed (OS Error: Operation not permitted, errno = 1), address = example.com, port = 443

Short 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.

  • Applies to Flutter 3.3x stable, macOS 15 and 26, Xcode 26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which network entitlements both macOS entitlement files already hold.

    grep -n "network" macos/Runner/*.entitlements
  2. 2Match what you see, then jump to its fix

    1. 1Every request fails with errno = 1 on macOS while the same code works on Android, iOS and webThe outgoing network entitlement is missingFix
    2. 2It 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

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.entitlements

2Fix

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 macos

Confirmed by docs.flutter.dev

Did this fix it?

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/*.entitlements

2Fix

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 macos

Confirmed by docs.flutter.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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