Launch Sale!

33% off all my courses

Code with Andrea Pro has launched!

View Offer

Flutter & Firebase Auth on macOS: Resolving Common Issues

Source code on GitHub

If you’ve used the Firebase Auth package before, you’ve probably noticed that macOS is listed as one of the supported platforms.

But as it turns out, getting even a very basic Flutter & Firebase app to run on macOS is a challenge, fraught with many perils. 😰

And to help you overcome all the hurdles, I’ve prepared this step-by-step guide.

Why this guide?

macOS is my target platform of choice when writing Flutter apps, for three reasons:

  1. it supports hot reload (just like iOS and Android)
  2. it doesn't use a ton of CPU/memory (I'm looking at you, Android Emulator)
  3. the window is resizable (making it easy to test responsive UIs)

But if you add Firebase to the mix and try to run your Flutter app on macOS, all sorts of errors show up, and you're likely to waste a few hours on StackOverflow just to get things working again.

To save you some time and frustration, I decided to write this guide and share my findings.

In sharing this, I also hope that the FlutterFire maintainers will take notice and make it easier for developers to work with Flutter & Firebase on macOS. To that effect, I shared some criticism and suggestions at the end.

How does this guide work?

To focus on the problem at hand, I’m sharing a simple Flutter & Firebase app that already contains a simple authentication flow and works as intended on all other platforms (iOS, Android, web):

Simple authentication flow with Firebase UI
Simple authentication flow with Firebase UI

But as we’ll see, we’ll encounter a series of errors if we try to run the same app on macOS.

You can find the source code for the whole app here:

Getting Started

If you want to get the sample app running, follow these initial steps:

  • clone the GitHub repo and open it in VSCode
  • create a new project in the Firebase console and follow all the steps to add a Flutter app
  • run flutterfire configure so all the Firebase configuration files are added
flutterfire configure --project=your-firebase-project-id

Once you’ve done this, the app should run correctly on iOS, Android, and web.

And with that, let’s tackle macOS.

Content warning: this guide contains some sarcasm. 😬

Missing file libarclite_macosx.a

When running the app on macOS, the first error I’ve encountered is this:

File not found: libarclite_macos.a
File not found: libarclite_macos.a

As it turns out, there is a similar issue on iOS, which has been discussed on StackOverflow:

To solve this, I've adapted the code from this answer by replacing this code at the end of the macos/Podfile:

post_install do |installer| installer.pods_project.targets.each do |target| flutter_additional_macos_build_settings(target) end end

with this:

post_install do |installer| # Ensure pods also use the minimum deployment target set above # https://stackoverflow.com/a/64385584/436422 puts 'Determining pod project minimum deployment target' pods_project = installer.pods_project deployment_target_key = 'MACOSX_DEPLOYMENT_TARGET' deployment_targets = pods_project.build_configurations.map{ |config| config.build_settings[deployment_target_key] } minimum_deployment_target = deployment_targets.min_by{ |version| Gem::Version.new(version) } puts 'Minimal deployment target is ' + minimum_deployment_target puts 'Setting each pod deployment target to ' + minimum_deployment_target installer.pods_project.targets.each do |target| flutter_additional_macos_build_settings(target) target.build_configurations.each do |config| config.build_settings[deployment_target_key] = minimum_deployment_target end end end

The platform version also needs to be set at the top of the Podfile:

platform :osx, '10.14'

At this stage, we can run the app again and marvel at these scary-looking logs on the console:

Some Xcode build warnings
Some Xcode build warnings

As it turns out, these are only warnings, and the app actually starts:

Sign in page on macOS
Sign in page on macOS

But let’s not be fooled by the appearances! For we’re about to encounter a bunch of runtime errors. 👇

Network error (such as timeout, interrupted connection or unreachable host) has occurred

If we try to sign in or create an account, this bad boy shows up!

Network error upon sign-in
Network error upon sign-in

To fix this, we can open the macos project in Xcode:

Opening the macOS project in Xcode
Opening the macOS project in Xcode

Then, open the “Signing & Capabilities” tab for the Runner target, and tick the “Outgoing Connections (Client)” checkbox under the “App Sandbox (Debug and Profile)” section:

Enabling Outgoing Connections (Client) in the App Sandbox section
Enabling Outgoing Connections (Client) in the App Sandbox section

Then, we can run the app from scratch and try to sign in again, only to be greeted with another error. 👇

An error occurred when accessing the keychain

This is such a lovely error message that I’m tempted to frame it in my office:

An error occurred when accessing the keychain. The NSLocalizedFailureReasonErrorKey field in the NSError.userInfo dictionary will contain more information about the error encountered

I’m sure my users would love to see this in production:

An error occurred when accessing the keychain
An error occurred when accessing the keychain

But clearly, it’s my fault. How could I possibly forget to add the “Keychain Sharing” capability in Xcode?

Enabling keychain sharing
Enabling keychain sharing

With that sorted, let’s run the app once again.

"Runner" has entitlements that require signing with a development certificate

This is the icing on the cake. 👇

"Runner" has entitlements that require signing with a development certificate

If we look carefully, Xcode also tells us the same thing. 👇

"Runner" has entitlements that require signing with a development certificate (Xcode)

Alright alright!

Assuming we already have an Apple developer account (who doesn’t? 😱), we can select it in the “Team” dropdown, click on “Enable Development Signing”, and Xcode will sort things out for us:

Enabling code signing in Xcode
Enabling code signing in Xcode

To sign your iOS and macOS apps, you need to enroll for an Apple developer account, which costs $99/year. 💰

Running one more time

Believe it or not, we’ve reached the end of this odyssey!

The app now runs correctly, and if we attempt to sign in, we’re redirected successfully to the profile page:

Success! After sign in, we're redirected to the profile page
Success! After sign in, we're redirected to the profile page

Bingo! 🎯

Conclusion

As we have seen, getting Flutter & Firebase Auth to work on macOS is simply a case of getting past these "trivial" errors:

  • Missing file libarclite_macosx.a
  • Network error (such as timeout, interrupted connection or unreachable host) has occurred
  • An error occurred when accessing the keychain
  • "Runner" has entitlements that require signing with a development certificate

On iOS, everything goes smoothly, and most certainly, code signing is not required just to debug the app on the simulator. So I’m very puzzled about why this is a thing on macOS.

Some Criticism

In sharing this guide, I genuinely wanted to help folks who, like me, have struggled with Flutter + Firebase + macOS.

But the current state of play doesn’t exactly scream “developer-friendly”.

In an ideal world, Flutter & Firebase apps should “just work” on macOS without jumping through all these hoops.

So I also hope the right people in the Flutter / Firebase / Invertase teams will take notice and make the necessary improvements.

To that extent, here are some suggestions:

  • improve flutterfire so it automatically takes care of all the macOS setup steps
  • add a page to official docs explaining all the steps (and keep it up to date)

For now, I hope this guide will suffice.

Thanks for reading, and happy coding!

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.