How to fix "SocketException: Connection failed (Operation not permitted)" with Flutter on macOS

Adding networking support to a Flutter app is a very common requirement.

This is mostly a case of following these steps:

  • install a networking package such as http or dio from pub.dev
  • add all the necessary networking code to your Flutter app
  • add any required API keys if needed

But if you run the app on macOS, you'll be welcomed by this scary error:

The SocketException error has come to visit you
The SocketException error has come to visit you

Here it is, in a more readable format:

DioError (DioError [DioErrorType.other]: SocketException: Connection failed (OS Error: Operation not permitted, errno = 1), address = api.themoviedb.org, port = 443 Source stack: #0 DioMixin.fetch (package:dio/src/dio_mixin.dart:488:35) #1 DioMixin.request (package:dio/src/dio_mixin.dart:483:12) #2 DioMixin.get (package:dio/src/dio_mixin.dart:61:12) #3 DioHttpService.get (package:movies_app/core/services/http/dio_http_service.dart:47:35)

So let's figure out why this happens and how to fix it. 👇

Note: if you're adding macOS support to an older Flutter app, you may need to run flutter create --platforms macos . to add macOS as a build target. I run most of my apps on macOS, so I can easily resize the window when building responsive UIs.

Client networking entitlements on macOS

macOS applications are sandboxed by default, and the SocketException error happens if you haven't added the required entitlements.

To fix this, open the file called macos/Runner/DebugProfile.entitlements and add the following:

<key>com.apple.security.network.client</key> <true/>

Then, open macos/Runner/Release.entitlements and do the same thing.

Once you're done, the entitlements file should look like this in Xcode:

DebugProfile.entitlements file with the client network entitlement
DebugProfile.entitlements file with the client network entitlement

What about iOS?

On iOS, the app will run just fine (no extra configuration is needed), provided that you're connecting to a secure https endpoint.

Though keep in mind that in certain cases, you may need to customise the app transport security settings as explained here:

What about Android?

On Android, it used to be necessary to add the INTERNET permission to the AndroidManifest.xml file:

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

But according to this answer, this is no longer needed since most apps need internet access.

Additional Resources

Want More?

Invest in yourself with my high-quality Flutter courses.

Flutter Foundations Course

Flutter Foundations Course

Learn about State Management, App Architecture, Navigation, Testing, and much more by building a Flutter eCommerce app on iOS, Android, and web.

Flutter & Firebase Masterclass

Flutter & Firebase Masterclass

Learn about Firebase Auth, Cloud Firestore, Cloud Functions, Stripe payments, and much more by building a full-stack eCommerce app with Flutter & Firebase.

The Complete Dart Developer Guide

The Complete Dart Developer Guide

Learn Dart Programming in depth. Includes: basic to advanced topics, exercises, and projects. Fully updated to Dart 2.15.

Flutter Animations Masterclass

Flutter Animations Masterclass

Master Flutter animations and build a completely custom habit tracking application.