DEV Community: Yevhen Beshkarov

Maven Central 403 or 429 in GitHub Actions: a Gradle fix

Yevhen Beshkarov — Wed, 11 Nov 2026 00:00:00 +0000

A Gradle build on a GitHub-hosted runner fails with a Maven Central 403: Received status code 403 from server: Forbidden for a file on repo.maven.apache.org. Or it gets 429, Too Many Requests. Nothing is wrong with your build. Maven Central limits the IP addresses that download the most, and GitHub's runners share their addresses with everyone else's jobs. A cache and retries don't fix it. Downloading less from Maven Central does: a Gradle init script that sends the downloads to Google's mirror of Maven Central, keeps Maven Central last for what the mirror doesn't have yet, and closes the path through the Gradle Plugin Portal.

The CI of SMF builds Flutter apps for Android in about 60 parallel jobs every night, and it has used this script since 2 October 2026. Since then it has run at least 3,917 Android jobs without one 403 or 429. The numbers below come from a fresh flutter create app (Flutter 3.44.2, Android Gradle plugin 9.0.1, Kotlin 2.3.20), built on my Mac with an empty Gradle home on 11 November 2026, with Gradle 9.1.0 and 9.9.1. The script itself has nothing specific to Flutter.

Received status code 403 from server: Forbidden

This is how it looked in our nightly run:

> Could not resolve all files for configuration ':app:debugRuntimeClasspath'.
   > Could not download listenablefuture-1.0.jar (com.google.guava:listenablefuture:1.0)
      > Could not get resource 'https://repo.maven.apache.org/maven2/com/google/guava/listenablefuture/1.0/listenablefuture-1.0.jar'.
         > Could not GET 'https://repo.maven.apache.org/maven2/com/google/guava/listenablefuture/1.0/listenablefuture-1.0.jar'. Received status code 403 from server: Forbidden

The rate limit looks the same, with Received status code 429 from server: Too Many Requests. Maven reports both as status code: 403, reason phrase: Forbidden (403) or 429, reason phrase: Too Many Requests (429). Gradle doesn't show the body of the answer, but if you request the file with curl from a blocked address, Sonatype, which runs Maven Central, now explains it there:

Error 403 Forbidden: This IP has been blocked for excessive or automated consumption of Maven Central

Maven Central 403 vs 429

Since 2026, Sonatype treats the two codes as different signals, as its FAQ on 429 errors and on 403 errors explains.

A 429 means you hit a consumption limit. The block is temporary, but it comes back and gets longer while the traffic stays the same, up to 30 days. Sonatype doesn't publish the limits, and it says that retries make things worse, so adding them to the workflow is the wrong fix.

A 403 means the traffic counts as abuse. Such a block may cover a subnet, and in extreme cases a whole autonomous system (ASN).

The terms of service of 31 March 2026 describe the model behind this: Maven Central stays free at levels that Sonatype considers reasonable, and high-volume consumers either reduce their traffic or pay.

Why GitHub-hosted runners get blocked

A job on a hosted runner leaves through IP addresses that many other jobs use too, and Sonatype counts the traffic per address and, since 2025, per organization behind several addresses. On 6 January 2026, Maven Central answered GitHub Actions with 403 for about four hours. The status page gives the cause: security rules of its CDN that GitHub Actions addresses triggered. The issue about it, actions/runner#4180, is still open with 75 upvotes, and the only reply from GitHub links that status page.

Other CI services handled it on their side. In May 2026, Sonatype allow-listed the dedicated IP ranges of CircleCI, and Bitrise has routed Gradle builds through its own proxy by default since 30 April 2026. GitHub has an agreement that exempts its runners from the rate limits of Docker Hub, but I found nothing like it for Maven Central, so on GitHub Actions the fix is up to you.

It happens more and more. GitHub issues that mention repo.maven.apache.org and Forbidden went from 11 in 2024 to 45 in 2025 and 108 in 2026, up to 11 November. Even the CI of Gradle itself ran into 429 in September (gradle/gradle#39257).

Why the Gradle cache does not fix the Maven Central 403

Our job above did restore a cache of Gradle, just not its own. When a job doesn't find the cache for its key, actions/cache restores the newest one under a shorter prefix, and that came from an app with Firebase. In that app, Guava replaces com.google.guava:listenablefuture:1.0 with an empty version, 9999.0-empty-to-avoid-conflict-with-guava, so the cache had no listenablefuture-1.0.jar. Gradle went to Maven Central for it. In that run, 27 Android jobs topped up their caches from Maven Central, and one of them got the 403.

A cache cuts the number of downloads. It doesn't take Maven Central out of the build: every new dependency, every new version, and every cache that misses a file still goes there.

Google's mirror of Maven Central

Google keeps a copy of Maven Central in Cloud Storage, in three regions:

https://maven-central.storage-download.googleapis.com/maven2/
https://maven-central-eu.storage-download.googleapis.com/maven2/
https://maven-central-asia.storage-download.googleapis.com/maven2/

Maven Central lists these three in its own repository-metadata.xml. Google's page about the mirror says that it isn't an officially supported product, so there is no SLA.

The page also says that the American copy is updated 12 times a day. That isn't what I measured. I compared the Last-Modified dates of the daily releases of software.amazon.awssdk:s3 on both hosts:

Version	On Maven Central (UTC)	On the mirror (UTC)	Delay
2.57.9	4 Nov, 22:48	6 Nov, 02:15	27.5 h
2.57.10	5 Nov, 23:17	7 Nov, 02:23	27 h
2.57.11	6 Nov, 22:16	8 Nov, 02:23	28 h
2.57.12	9 Nov, 21:56	11 Nov, 02:17	28.5 h
2.57.13	11 Nov, 01:45	not there at 09:27	over 7.5 h

New files reach the mirror once a day, at about 02:15 UTC, a day or more after they appear on Maven Central. A build whose dependency came out yesterday fails on the mirror alone. We hit that on 22 October: purchases_flutter 10.18.1 needed com.revenuecat.purchases:purchases-hybrid-common:19.15.0, the mirror answered 404, and 10 jobs failed with Could not find. So the mirror goes first, and Maven Central stays last for what the mirror doesn't have yet.

The init script: mirror first, Maven Central last

Put this file into ~/.gradle/init.d/ on the runner, and Gradle applies it to every build there, whatever the build declares:

// Takes what Gradle would download from Maven Central from Google's mirror,
// and from Maven Central only what the mirror does not have yet.

def central = ~/^https:\/\/(repo\.maven\.apache\.org|repo1\.maven\.org)\/maven2\/?/
def mirror = 'https://maven-central.storage-download.googleapis.com/maven2/'
def fallback = 'mavenCentralBehindMirror'

def addFallback = { RepositoryHandler repositories ->
    repositories.maven {
        name = fallback
        url = 'https://repo.maven.apache.org/maven2/'
    }
}

def toMirror = { RepositoryHandler repositories ->
    def hasFallback = false
    // all, not configureEach: a configureEach action may not add or move a repository.
    repositories.all { repository ->
        if (repository.name == fallback) {
            return
        }
        if (repository instanceof MavenArtifactRepository) {
            def url = repository.url.toString()
            if (url =~ central) {
                // In place, so the order of the repositories stays.
                repository.url = url.replaceFirst(central, mirror)
                if (!hasFallback) {
                    hasFallback = true
                    addFallback(repositories)
                    return
                }
            }
        }
        // Keep Maven Central last when the build adds a repository later.
        def last = repositories.findByName(fallback)
        if (hasFallback && !repositories.last().is(last)) {
            repositories.remove(last)
            repositories.add(last)
        }
    }
}

beforeSettings { settings ->
    toMirror(settings.buildscript.repositories)
    toMirror(settings.pluginManagement.repositories)
    toMirror(settings.dependencyResolutionManagement.repositories)
}

settingsEvaluated { settings ->
    // A build without plugin repositories goes to the Gradle Plugin Portal,
    // which redirects to Maven Central whatever it does not host itself.
    if (settings.pluginManagement.repositories.isEmpty()) {
        settings.pluginManagement.repositories { repositories ->
            maven { url = mirror }
            addFallback(repositories)
            gradlePluginPortal()
        }
    }
}

allprojects { project ->
    toMirror(project.buildscript.repositories)
    toMirror(project.repositories)
}

What it does:

It finds Maven Central by its URL, not by the name of the repository, so mavenCentral() and maven { url = "https://repo1.maven.org/maven2/" } both count. It changes the URL in place, so google() and the other repositories keep their order.
Every list of repositories in which it changed one gets Maven Central itself at the end. Gradle asks the repositories of a list in order and moves on when one doesn't have a module, so Maven Central gets only what nothing before it has. The script keeps it last when the build adds a repository later, as the Gradle plugin of Flutter does with its own storage.
It covers the settings, the build scripts and the projects of every build, including included builds such as the one of the Gradle plugin of Flutter.
A build that declares no plugin repositories gets the mirror and Maven Central before the Gradle Plugin Portal. The next section explains why.

The workflow puts the file into place before the first step that runs Gradle:

- name: Take what Gradle downloads from Maven Central from its mirror
  run: |
    mkdir -p ~/.gradle/init.d
    cp .github/gradle/maven_central_mirror.gradle ~/.gradle/init.d/

If your job sets GRADLE_USER_HOME, the script goes into init.d there. gradle/actions/setup-gradle adds an init script of its own to the same directory, and Gradle runs both.

The Gradle Plugin Portal sends you back to Maven Central

A mirror for mavenCentral() isn't enough. Since July 2024, the Gradle Plugin Portal answers 303 See Other with an address on repo.maven.apache.org for every artifact it doesn't host itself. The portal serves the jar of the Kotlin Gradle plugin, but not the plugin's dependencies: kotlin-gradle-plugin-api, kotlin-stdlib, kotlinx-coroutines-core-jvm, Gson and others. Gradle follows the redirect without a word, so the output only shows plugins.gradle.org.

In the Flutter app, 60 files reached Maven Central this way. A build that declares no plugin repositories in pluginManagement, such as the included build of the Gradle plugin of Flutter, uses the portal without listing it, so no rewrite of a URL reaches it. That's what the settingsEvaluated block is for: the mirror and Maven Central go in front of the portal, and the portal only gets the plugin markers and jars that it hosts itself.

Don't point the portal at the mirror instead. Google's mirror has only Maven Central, and the build fails on the first plugin it looks up.

Gradle 9.8 and the init script of the Gradle blog

Gradle has two answers of its own, and neither handles the lag of the mirror or the portal.

The Gradle blog post Good Neighbors (August 2025) has an init script that points the repositories named MavenRepo and Gradle Central Plugin Repository at one URL. It is written for an internal proxy that serves both Maven Central and the Plugin Portal. With Google's mirror as that URL, the Flutter build fails right away:

Plugin [id: 'org.gradle.kotlin.kotlin-dsl', version: '6.2.0'] was not found in any of the following sources:
...
    Gradle Central Plugin Repository(https://maven-central.storage-download.googleapis.com/maven2/)

When I let it change only MavenRepo, the build worked, but the 60 redirects through the portal stayed.

Gradle 9.8.0, released on 24 September 2026, can read <mirror> entries from Maven's ~/.m2/settings.xml when org.gradle.mirror.maven.settings=true is set. The feature is incubating. With <mirrorOf>central</mirrorOf> pointing at Google's mirror, Gradle 9.9.1 took nothing directly from Maven Central, but 52 files still came from there through the portal. And a version published that morning, org.jetbrains.kotlin:kotlin-stdlib:2.5.0-RC, failed to resolve, since a Maven mirror replaces the repository and leaves no fallback. A new Flutter app doesn't have the feature until you update its Gradle wrapper: flutter create writes Gradle 9.1.0 with Flutter 3.44 and 9.3.1 with 3.47.

	Directly from Maven Central	Through the Plugin Portal	Build
Nothing, Gradle 9.1.0	332 requests	60 files	works
Gradle blog script, Google's mirror	0	0	fails on the first plugin
Gradle 9.9.1, mirror from `settings.xml`	0	52 files	works, no fallback
The script above	0 downloads	0	works, with fallback

Check that nothing reaches Maven Central

Run the build once with an empty Gradle home and the script in it, then count the hosts:

export GRADLE_USER_HOME="$(mktemp -d)"
mkdir -p "$GRADLE_USER_HOME/init.d"
cp maven_central_mirror.gradle "$GRADLE_USER_HOME/init.d/"
./gradlew --debug assembleDebug 2>&1 \
  | grep -oE "Performing HTTP (GET|HEAD): https://[^/]+|Redirect requested to location 'https://[^/]+" \
  | sort | uniq -c | sort -rn

The Redirect lines matter: without them, the portal's trips to Maven Central don't show. For the Flutter app, the output was:

 387 Performing HTTP GET: https://maven-central.storage-download.googleapis.com
 380 Performing HTTP GET: https://dl.google.com
  14 Performing HTTP HEAD: https://dl.google.com
   8 Performing HTTP GET: https://storage.googleapis.com
   4 Performing HTTP GET: https://plugins.gradle.org
   3 Redirect requested to location 'https://plugins-artifacts.gradle.org
   2 Performing HTTP HEAD: https://maven-central.storage-download.googleapis.com
   2 Performing HTTP GET: https://repo.maven.apache.org
   1 Performing HTTP HEAD: https://plugins.gradle.org

No redirect leads to Maven Central. The two requests to repo.maven.apache.org are 404s, not downloads: the org.gradle.kotlin.kotlin-dsl plugin and its marker are neither on the mirror nor on Maven Central, so Gradle finds them on the portal, which comes next in the list.

How SMF keeps its CI off Maven Central

SMF is a free, open-source Flutter project generator, and its CI generates and builds apps from combinations of its modules for pull requests and every night. Every job that runs Gradle on Linux first puts the same script into ~/.gradle/init.d, and a test of the workflows fails when a new job forgets it. From 2 October to 11 November 2026, that was at least 3,917 Android jobs with no 403 and no 429. The one failure from a Maven repository in that time was the lag of the mirror on 22 October, and that's why Maven Central now stays last. Since the shared_preferences release build crash, which no debug build shows, the same CI also starts a generated app as a release build on an emulator.

Fix "APNS token has not been set yet" in Flutter on iOS

Yevhen Beshkarov — Thu, 05 Nov 2026 00:00:00 +0000

On iOS, Firebase delivers push notifications through Apple's push service (APNs), so FirebaseMessaging.instance.getToken() refuses to run until Apple has given the device its APNs token. Called earlier, it throws apns-token-not-set, which older versions of firebase_messaging describe as "APNS token has not been set yet". Usually the app just asked too early. How it should wait depends on the version: firebase_messaging 17 tells the app when Firebase is ready, and 16.7 doesn't. In a few setups, though, Apple never answers, however long the app waits.

I checked everything below on an iPhone 17 simulator with iOS 26.5, Xcode 27.2 and Flutter 3.44.2, with firebase_messaging 16.7.1 (Firebase iOS SDK 12.19.3) and 17.0.1 (Firebase iOS SDK 13.1.1).

APNS token has not been set yet, or has not been received on the device yet

The error comes in two wordings. Older versions say:

[firebase_messaging/apns-token-not-set] APNS token has not been set yet. Please ensure the APNS token is available by calling `getAPNSToken()`.

Since October 2025 (firebase_messaging 16.0.3, with firebase_messaging_platform_interface 4.7.3), the same error says:

[firebase_messaging/apns-token-not-set] APNS token has not been received on the device yet. Please ensure the APNS token is available before calling `getAPNSToken()`.

Both are a FirebaseException with the code apns-token-not-set, so check the code rather than the text. The hint to call getAPNSToken() is misleading, because that call never throws. It returns null until Apple has answered, which makes it the thing to wait on.

The check runs in Dart, before anything reaches iOS. getToken(), deleteToken(), subscribeToTopic() and unsubscribeFromTopic() all start with it. So a topic subscription at startup fails with the same error, while requestPermission() and onMessage work. If you use Firebase from Swift, the native SDK reports the same situation as No APNS token specified before fetching FCM Token.

Why getToken() fails right after the app starts

At launch, the plugin asks iOS to register the app for remote notifications, and iOS answers later, in application:didRegisterForRemoteNotificationsWithDeviceToken:. The Firebase iOS SDK keeps that answer in memory only. So an early getToken() fails on every launch, not just the first one, even when Firebase gave the app its FCM token on the previous launch.

How long the answer takes varies: about half a second on a simulator that had been running for a while, and about 30 seconds right after the simulator booted. On a phone, it depends on the network.

I checked this with a small app that calls getToken() right after Firebase.initializeApp(), after a fresh install and after a restart, with both versions. The call failed every time, although Apple answered within a second. What differs between the versions is whether the app learns that Firebase is ready.

firebase_messaging 16: wait for getAPNSToken()

With 16.7.1, the Firebase iOS SDK requests the FCM token by itself as soon as Apple answers (the log shows the app connecting to fcmtoken.googleapis.com), but the plugin doesn't pass it on to Dart: onTokenRefresh stayed silent for the 20 seconds I waited, after a fresh install and after a restart. So the app has to wait for getAPNSToken() itself, then call getToken():

import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter/foundation.dart';

/// The FCM token of this device once Apple has answered, or `null` when
/// Apple hasn't within [limit].
Future<String?> pushTokenWhenReady({
  Duration limit = const Duration(minutes: 2),
}) async {
  final messaging = FirebaseMessaging.instance;
  if (!kIsWeb && defaultTargetPlatform == TargetPlatform.iOS) {
    var wait = const Duration(milliseconds: 500);
    var waited = Duration.zero;
    while (await messaging.getAPNSToken() == null) {
      if (waited >= limit) return null;
      await Future<void>.delayed(wait);
      waited += wait;
      if (wait < const Duration(seconds: 8)) wait *= 2;
    }
  }
  return messaging.getToken();
}

Don't await it before runApp(). I found apps on GitHub that opened to a white screen on iOS for exactly this reason: main() waited, getToken() threw, and runApp() never ran. Start the app first and send the result to your server when it arrives:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  runApp(const MyApp());
  final token = await pushTokenWhenReady();
  if (token != null) await sendTokenToServer(token);
}

If the wait runs out, try again when the user comes back to the app, for example from an AppLifecycleListener with onResume.

firebase_messaging 17: listen to onTokenRefresh

Since 17.0.0, released in October 2026, the plugin becomes the delegate of the Firebase iOS SDK during Firebase.initializeApp(), so onTokenRefresh gets two events that 16 lost. After a fresh install, it fires as soon as the SDK has the FCM token, in my runs 1.4 seconds after Apple answered. On every later launch, it fires right at startup with the value that the SDK saved last time: 0.2 seconds after main() started, before Apple had answered and while getToken() still threw.

So on 17, subscribe to onTokenRefresh right after initializeApp(), and keep the getToken() call for Android, where it doesn't depend on Apple:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  final messaging = FirebaseMessaging.instance;
  messaging.onTokenRefresh.listen(sendTokenToServer);
  runApp(const MyApp());
  try {
    final token = await messaging.getToken();
    if (token != null) await sendTokenToServer(token);
  } on FirebaseException catch (e) {
    // On iOS before Apple has answered: onTokenRefresh delivers it.
    if (e.code != 'apns-token-not-set') rethrow;
  }
}

Your server may get the same value twice this way, so it should accept one that it already has. Subscribe early, because onTokenRefresh is a broadcast stream and a listener that comes after the startup event never sees it. If your code subscribes later, after a sign-in for example, wait for getAPNSToken() as with 16.

Firebase is also moving Cloud Messaging from registration tokens to the Firebase Installation ID (FID). Version 17 deprecates getToken(), onTokenRefresh and deleteToken() in favor of register(), onRegistered and unregister(), and flutter analyze exits with code 1 on the code above because of the deprecation infos. I haven't tried the FID path yet, so this article stays with getToken().

When the APNs token never comes

If getAPNSToken() still returns null after a minute, waiting longer won't help. These are the cases I know of.

No aps-environment entitlement

iOS registers an app for remote notifications only when the build is signed with the aps-environment entitlement, which Xcode adds with the Push Notifications capability in Signing & Capabilities. Without it, the Xcode console shows:

[FirebaseMessaging][I-FCM012002] Error in application:didFailToRegisterForRemoteNotificationsWithError: no valid "aps-environment" entitlement string found

The simulator follows the same rule. A build made with flutter build ios --simulator --no-codesign doesn't get the entitlement, and mine waited two minutes for Apple in vain.

A free Apple team

A personal team can't sign aps-environment. To run the app on an iPhone, you have to remove the capability, and then Apple never answers there. The simulator doesn't need a team, since Xcode signs simulator builds ad hoc.

The iOS simulator on GitHub Actions

The iOS simulator on a Mac gets a real APNs token. On a macOS virtual machine it never does, and the macOS runners of GitHub Actions are virtual machines. I tried a macos-26 runner: the app was built with the entitlement, nothing came in four minutes, and the push daemon logged no token info found in keychain before it disconnected. actions/runner-images#12747 reports the same for macos-15. A CI job on a hosted runner can check that the app starts without push notifications, but not that it gets them.

firebase_messaging 16.5.0 and 16.6.0

These two versions skipped the registration for remote notifications at launch in two common setups: when Firebase is initialized from Dart, as with Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform) (flutterfire#18643), and in apps with scenes (flutterfire#18555), which the iOS template of current Flutter creates with SceneDelegate.swift. getAPNSToken() then stayed null on every launch. Version 16.7.0 fixed both. Check which version your app has:

flutter pub deps | grep firebase_messaging

Auto-init is off

With FirebaseMessagingAutoInitEnabled set to NO in Info.plist, or after setAutoInitEnabled(false), the plugin doesn't register for remote notifications. Call setAutoInitEnabled(true) before you start waiting.

Not the APNs key

The APNs key in the Firebase console doesn't belong on this list. Firebase needs it to send messages through Apple, so without it nothing arrives, but getAPNSToken() and getToken() work all the same.

How SMF handles push notifications on iOS

The firebase_messaging module of SMF, a free, open-source Flutter project generator, gives the app the address of the device as appPush.address, which stays null until Firebase has one. The first frame never waits for it. On iOS, the module polls getAPNSToken() as above, waiting from half a second up to eight seconds between tries, for at most two minutes, and asks again whenever the user comes back to the app. It adds aps-environment and the background mode remote-notification, and the README of the app explains what to do with a free team. Uploading the APNs key stays a step you do by hand. SMF's CI starts the apps on the iOS simulator of a hosted runner, where they have to start and work without an address.

SMF 0.8: Flutter flavors, CI and a REST client

Yevhen Beshkarov — Mon, 02 Nov 2026 00:00:00 +0000

Say My Frame (SMF) generates Flutter apps from independent modules. Version 0.8 is out on pub.dev, and it covers what an app needs before it goes to the stores: Flutter flavors, CI, a REST client, and an icon and a splash screen that are not the ones of Flutter.

dart pub global activate smf_flutter_cli
smf create my_app -m home,bottom_tabs,material_theme,gen_l10n,dio,github_actions,launcher_icons,native_splash

As before, you get a regular Flutter project with no SMF package in its dependencies, and SMF never touches it again.

Flutter flavors in every app

Every app now has dev, staging and prod. You don't ask for them, and no package stands behind them: they are plain Gradle and Xcode settings. Each flavor has its own id and its own name, so all three sit next to each other on one phone.

flutter run builds dev. So does any other flutter command without --flavor, in release mode too, which means flutter build appbundle gives you a release of your dev app. A build for a store always names the flavor. In an app with values in .env, it takes those too:

flutter build appbundle --flavor prod --dart-define-from-file=.env

With firebase_core, each flavor has its own Firebase apps, in one project or in several. In a terminal, smf create configures dev, and each other flavor takes one command:

dart tool/configure_firebase.dart staging --project=my-app-staging

.env is the one thing that does not follow the flavor. There is one file, and a command takes what the file has when it runs. On your machine you change the values by hand, and in CI the job writes the file for the environment that it builds. The guide to flavors has the rest, such as adding a fourth flavor.

CI on GitHub Actions

github_actions adds .github/workflows/ci.yml. Each push to a branch checks the format and runs the analyzer and the tests, with nothing to set up first.

A build of the Android app runs on request, for the environment that you pick, with the values of .env from the variables of that environment on GitHub:

gh workflow run ci.yml -f environment=staging

The CI guide lists the commands and where the variables go.

A REST client with its address in .env

dio gives the app appRest, a client that reads the address of your API from REST_BASE_URL in .env:

final response = await appRest.get('notes', query: {'page': '1'});

No screen of the app makes a request on its own, since the client is there for the code that you add. What it does for that code is the part I didn't want to leave to each app:

GET and HEAD repeat after a connection that failed and after 429, 502, 503 and 504. Other methods never repeat, since a repeated POST may do its work twice.
In an app with sign-in, the client adds the token of the user, gets a new one once after a 401, and takes the token away on a redirect to another origin.
A call fails only with a RestFailure, which has a closed set of reasons.

The REST guide covers the rest.

An app icon and a splash screen

launcher_icons and native_splash replace the logo of Flutter and the white launch screen with the mark of SMF, and the splash screen has a variant for the dark mode of the device. To use your own, replace the images in assets/branding/ and run:

dart tool/update_app_icon.dart
dart run flutter_native_splash:create

The guide to the icon and the splash screen gives the sizes of the images.

Upgrading from 0.7

Apps generated by 0.7 stay as they are, since SMF generates an app once.
If you write modules, smf_contracts changed: a provider of the app entry writes the flavors into its native projects, and a provider of sign-in implements userToken.
A module that reads lib/firebase_options.dart needs an update, since each flavor now has lib/firebase_options_<flavor>.dart.

The full list is in the release notes of SMF 0.8.0 on GitHub.

What comes next

Next on my list are the rating of the app in the stores, reviews, remote config and ads. There are no dates: SMF is a side project. If you have a module in mind, tell me on Discord or in GitHub Issues.

SMF generates Android and iOS apps for Flutter 3.44 or newer and Dart 3.12 or newer. The documentation starts with installation and your first app, and the code is on GitHub.

Fix Google Sign-In [28444] in Flutter with google_sign_in 7

Yevhen Beshkarov — Thu, 29 Oct 2026 00:00:00 +0000

Since version 7, google_sign_in signs users in on Android through Credential Manager, and a broken setup shows up as one of a few messages. The best known is [28444] Developer console is not set up correctly, and the checklists for it usually start with the SHA-1. I reproduced each case on an emulator, and with current Google Play services a missing SHA-1 doesn't give the app this error at all. The app gets a canceled with Account reauth failed instead. 28444 showed up when the app sent the wrong client ID.

Everything below was checked on an Android 17 emulator with Google Play services 26.41, google_sign_in 7.2.0 and google_sign_in_android 7.2.18, against a Firebase project. Before version 7, the plugin reported a broken setup as ApiException: 10, the DEVELOPER_ERROR of Google Play services.

What each Google Sign-In error means

GoogleSignIn.instance.authenticate() throws a GoogleSignInException. The code and the description tell the cases apart:

Description	Code	What is wrong
`[28444] Developer console is not set up correctly.`	`unknownError`	Google doesn't take the `serverClientId` as the web client of the app: it is the ID of the Android client, or a client that doesn't exist
`serverClientId must be provided on Android`	`clientConfigurationError`	The app has no web client ID at all: `google-services.json` has none, or the release build dropped it
`[16] Account reauth failed.`	`canceled`	No Android OAuth client with the package name of the app and the SHA-1 of the key that signed it, or no connection to Google
`[16] Cancelled by user.`	`canceled`	The user closed the sheet, or backed out of adding a Google account

The two cases of canceled share a code. The README of the plugin warns about this: it can't tell some setup errors from a user who cancelled. attemptLightweightAuthentication() hides a missing SHA-1 completely and just returns null.

logcat prints GetCredentialResponse error returned from framework for every failure, a plain cancel included, so that line doesn't point to the cause. And on a device or an emulator without a Google account, the sign-in never gets far enough to fail: Credential Manager opens the screen that adds an account. Add one before you test the setup.

See the real cause in logcat

Google Play services logs what its server answered. Filter logcat to its two tags while you try to sign in:

adb logcat -s Auth:W Auth.Api.Credentials:W

For a missing SHA-1, the first lines are:

W Auth : [GetTokenResponseHandler] Server returned error: This android application is not registered to use OAuth2.0, please confirm the package name and SHA-1 certificate fingerprint match what you registered in Google Developer Console.
W Auth.Api.Credentials: cwsp: [8] Unknown error [status=UNREGISTERED_ON_API_CONSOLE].
W Auth.Api.Credentials: cwsp: [16] Account reauth failed.

For a wrong client ID, the same tags show 28444: Developer console is not set up correctly.

[28444] Developer console is not set up correctly: the wrong client ID

To give the app an ID token, Google needs the client ID of a web application OAuth client, which google_sign_in sends as serverClientId. When Google doesn't accept that ID, the app gets:

GoogleSignInException(code GoogleSignInExceptionCode.unknownError, [28444] Developer console is not set up correctly., null)

I got it in two ways. The first was passing the ID of the Android client to initialize(): a Firebase project has both kinds, and they look alike, <number>-<letters>.apps.googleusercontent.com. The second was an ID that doesn't exist, as with a typo or a client deleted in the Google Cloud console.

In google-services.json, the web client is the one with "client_type": 3, and the Android clients have "client_type": 1. To print the web client ID:

grep -B1 '"client_type": 3' android/app/google-services.json | grep -m1 client_id

If you pass the ID yourself, pass that one:

await GoogleSignIn.instance.initialize(
  serverClientId: '1234567890-abc123.apps.googleusercontent.com',
);

With a google-services.json that has a web client, you don't need to pass anything: the plugin reads the ID from the resources that the Google services Gradle plugin generates from that file.

The checklists aren't wrong to mention the SHA-1, though. Inside Google Play services, a missing SHA-1 is 28444 too: logcat shows cwsp: [28444] when attemptLightweightAuthentication() runs into one, even though the app only gets null. I can't rule out that other versions of Play services pass it on to the app. If the client ID is right, check the SHA-1 next.

Account reauth failed: the SHA-1 of the signing key is missing

Google recognizes an Android app by its package name and the SHA-1 of the certificate that signed it. With Firebase, adding a SHA fingerprint to the Android app creates the Android OAuth client that Google looks for. When there is none, the user picks an account and the app gets:

GoogleSignInException(code GoogleSignInExceptionCode.canceled, [16] Account reauth failed., null)

The same message shows up in two other cases. When the device can't reach Google (on the emulator I turned off Wi-Fi and mobile data), logcat shows [7] Network error. right before it. And in flutter/flutter#190296, an app with a correct setup got it on every sign-in after the first one. The reporter fixed it by calling GoogleSignIn.instance.signOut() on sign-out. I tried that on the same emulator: eight sign-ins in a row without signOut(), some right after the app's own sign-out, and all of them worked. So it may depend on something that report had and my setup didn't, such as a physical device, an older plugin or an app installed from Google Play. logcat tells the cases apart: a missing SHA-1 shows not registered to use OAuth2.0, and no network shows Network error.

Find the SHA-1 of the build that fails

Gradle prints the key that signs each build type, and it is not always the one you expect:

cd android && ./gradlew signingReport


Variant: release
Config: debug
Store: /Users/you/.android/debug.keystore
Alias: AndroidDebugKey
SHA1: 60:45:3E:2E:7F:82:01:EC:F4:84:F8:43:A2:44:70:F9:4D:F9:7B:F5

A new Flutter app signs its release build with the debug key too (signingConfig = signingConfigs.getByName("debug") in android/app/build.gradle.kts), until you give it a key of its own. From then on, the release needs that key's SHA-1.

For an APK you already have, read the certificate from the file with apksigner from the Android SDK build tools:

$ANDROID_HOME/build-tools/<version>/apksigner verify --print-certs build/app/outputs/flutter-apk/app-release.apk

keytool -printcert -jarfile app.apk from Google's client authentication guide prints Not a signed jar file for a Flutter APK. Flutter sets minSdk to 24, and from that level on, the APK has only a v2 signature, which keytool doesn't read.

Some keys are easy to forget. Every machine has its own ~/.android/debug.keystore, so a teammate's debug build has a different SHA-1, and so does a CI runner that creates a fresh key. Google Play adds two more: your upload key, and the app signing key. With Play App Signing, users install a build that Google signed with its own key, and its SHA-1 is in the Play Console, under Test and release > App integrity > App signing.

Add the SHA-1 to Firebase

In the Firebase console, open Project settings, pick the Android app under Your apps and click Add fingerprint. Add the SHA-256 too. The Firebase CLI does the same, with the app ID from firebase apps:list ANDROID:

firebase apps:android:sha:create <appId> <sha1>

You don't need to download google-services.json again for this: the app never reads the Android clients from it. In my test, the same build signed in about 40 seconds after I added the SHA-1, with the old file.

Every SHA you add creates another Android OAuth client in the project, and Google caps the number of them. Removing a SHA from Firebase doesn't remove its client. Once the project is full, apps:android:sha:create fails with Failed to create SHA certificate hash, and only --debug shows the answer of the API: 429 Number of OAuth clients created exceeded limit. I ran into that because the CI of SMF registered the fresh debug key of every runner. Give CI one debug keystore that doesn't change, and register its SHA-1 once.

serverClientId must be provided on Android: no web client in google-services.json

When you don't pass serverClientId, google_sign_in_android reads the string resource default_web_client_id. The Google services Gradle plugin generates it from the web client in android/app/google-services.json. Without it, authenticate() fails at once, before any Google screen:

GoogleSignInException(code GoogleSignInExceptionCode.clientConfigurationError, serverClientId must be provided on Android, null)

The usual cause is a google-services.json downloaded before Google sign-in was enabled in Firebase Authentication. That file has "oauth_client": [], and the build gets no default_web_client_id. Check your file:

grep -c '"client_type": 3' android/app/google-services.json

0 means no web client. Enable Google in the Firebase console, under Authentication > Sign-in method, then download the file again, from Project settings or with the Firebase CLI:

firebase apps:sdkconfig ANDROID <appId> --out android/app/google-services.json

Also check that android/app/build.gradle.kts applies the com.google.gms.google-services plugin, which FlutterFire CLI adds when it configures the app. Without it, nothing generates the resource.

Works in debug, fails in release

When Google Sign-In works in debug builds and fails in the release, the message tells you which of two things happened.

If the release fails with [16] Account reauth failed., Firebase doesn't know the key of the release: your release key, or, for a build from Google Play, the app signing key of Google Play. Add its SHA-1 as above.

If it fails with serverClientId must be provided on Android, the release build lost default_web_client_id. Flutter shrinks the resources of a release build by default, and the plugin looks the string up by its name at run time, which the shrinker doesn't see. Up to google_sign_in_android 7.2.15, the shrinker removed it from every app (flutter/flutter#188363). Version 7.2.16 added a keep rule in res/raw/keep.xml of the plugin (flutter/packages#12075).

That rule has a catch (flutter/flutter#194943, open as I write this, with two pull requests that rename the plugin's file under review). If your app has its own android/app/src/main/res/raw/keep.xml, for example to keep a notification icon, Gradle merges the resources by file name, and the app's file replaces the plugin's. With 7.2.18, the release build then fails with serverClientId must be provided on Android. The shrinker says why:

grep default_web_client_id build/app/outputs/mapping/release/resources.txt


string:default_web_client_id:2131689529 is not reachable.

Rename your file, for example to res/raw/app_keep.xml. The Android guide to keeping resources asks for unique names for exactly this reason, and the shrinker reads every keep file in res/raw. After the rename, the same line says reachable from keep xml file, and sign-in works. You can also add @string/default_web_client_id to the tools:keep of your own file. Either way, check that the app has 7.2.16 or later:

flutter pub deps | grep google_sign_in_android

A CI that builds only debug never sees either case. The same thing happened with the shared_preferences release build crash, where R8 broke a plugin only in release builds, so start a release build on an emulator before your users do.

How SMF sets up Google Sign-In with Firebase

I went through all of this while building the google_sign_in module of SMF, a free, open-source Flutter project generator. In an app with the firebase_auth module, SMF generates a script, tool/enable_firebase_sign_in.dart, and runs it after flutterfire configure once you agree. The script enables Google in the Firebase project, registers the SHA-1 and SHA-256 of the debug key of your machine, downloads google-services.json again with the web client in it, and writes the URL scheme of the iOS app. So a debug build signs in with Google from the first run, and a teammate runs the script once on their own machine. The keys of a release stay a step you do by hand, with the commands in the README of the app.

SMF 0.7: a Flutter paywall with RevenueCat

Yevhen Beshkarov — Tue, 27 Oct 2026 00:00:00 +0000

Say My Frame (SMF) generates Flutter apps from independent modules. Version 0.7 is out on pub.dev. It adds a Flutter paywall that sells premium access with RevenueCat, a subscription screen, Restore purchases on the settings screen, and an onboarding page that offers premium. The RevenueCat keys go into a .env file that the app reads at build time. At the end of the post about 0.6, subscriptions with a paywall were next on my list.

dart pub global activate smf_flutter_cli
smf create my_app -m home,onboarding,sign_in,google_sign_in,apple_sign_in,paywall,local_notifications,bottom_tabs,material_theme,gen_l10n,get_it,bloc

The recording answers the questions of smf create instead of passing -m. The paywall needs a provider of purchases and a place for its keys, so SMF adds revenuecat and dart_define and says why, as it does for the router and the settings screen.

As before, what you get is a regular Flutter project. It has no SMF package in its dependencies, and SMF never touches it again.

The Flutter paywall after smf create

paywall is a feature module with two screens. The paywall at /paywall shows, from the top:

a card in the colors of Say My Frame, with the app as a cell of the periodic table and Premium above its name, as on the start screen;
three benefits of premium access;
a card for each plan of the current offering, with the price that the store gives, its period and its free trial, such as $29.99 / year and 1 week free. A yearly plan that costs less than twelve months of the monthly one gets the badge Best value, and the paywall selects it;
the button that buys the selected plan, which says Start free trial, Subscribe or Buy, and below it what the plan costs after its trial;
the terms of the platform's store, and the links Restore purchases, Terms of Use and Privacy Policy.

The subscription screen at /paywall/subscription shows the user's plan, the day it renews, ends or ends its free trial, and a button to the store page where the user cancels it.

Most of what the paywall shows comes from the rules of the App Store and Google Play for a screen that sells a subscription. The full price of each period is the largest text of its card, and a yearly plan never shows its price per month, which Google Play does not allow. A plan with a trial says how long the trial lasts and what comes after it. The paywall tells how to cancel in each store's own words, and on iOS the Terms of Use link goes to Apple's standard license agreement until you give an address of your own. The close button stays in sight whenever there is a page below the paywall to go back to.

The paywall never navigates after a purchase. The route of the subscription screen asks for premium access, and a router guard stands for it. A tap on Subscription in the settings opens the paywall for a user without premium, and once the purchase goes through, the router closes the paywall and shows the subscription screen, so neither screen has to know about the other.

In an app with an onboarding, the module adds a page, Unlock premium, after the pages that ask for permissions. Its button shows the paywall over the onboarding, and Not now goes on without it. A user who already has premium doesn't see the page. The settings screen gets two rows: Subscription, which says whether premium is active, and Restore purchases, which shows below its title what it found.

Like the screens of sign-in, the paywall comes in a variant for BLoC and one for Riverpod, in both themes and both languages of the app. The paywall page of the docs has the rest.

RevenueCat keys in .env, read with --dart-define-from-file

revenuecat sells the plans of the default offering in a RevenueCat project, with purchases_flutter. Every plan unlocks the same entitlement, premium. The app needs the public API keys of the project: one for the App Store, one for Google Play, and one for RevenueCat's Test Store, where you can buy in a debug build before your products are in the stores.

These keys are the first values in SMF that you fill in after generation, so 0.7 adds a role for them. dart_define gives the app a .env file with a line for each key that its modules read. The file stays out of git, and .env.example with the same keys stays in. The app reads the values with --dart-define-from-file=.env:

flutter run --dart-define-from-file=.env

An edit of .env needs no code generation, and a fresh clone of the app builds with the empty values. The VS Code and Android Studio run configurations that SMF generates pass the argument, and in VS Code so do Run and Debug and the Testing view.

Everything in .env ends up in the app, where anyone can read it. RevenueCat's public keys are made for that. A secret key isn't, so the app refuses a key that starts with sk_.

Without a key, the app starts and runs without purchases. The paywall says that the plans are not available right now, and a debug build shows you which key is missing. RevenueCat stops a release build that is configured with a Test Store key, so the app takes that key only in a debug build.

Whose purchases they are, with sign-in and without

In an app with sign-in, the purchases follow the user of the session. Someone who buys before signing up keeps premium on the new account. After a sign-out, the next user of the device has none of those purchases, and signing in again brings them back. In an app without sign-in, the purchases belong to the device. The purchases guide shows how code reads premium access and the plans.

What RevenueCat did on real devices

Before writing the module, I ran purchases_flutter in a generated app on an iPhone simulator and an Android 12 emulator, with no key, with made-up keys, and with calls made in the wrong order:

On iOS, any call to RevenueCat before it is configured crashes the app. On Android the same call only throws. So the generated service calls nothing before its configuration has finished, and nothing at all without a key.
With an empty key, iOS configures anyway and sends requests that fail with 401. Android throws an error whose code is the word error, and the helper of the plugin that reads error codes throws a FormatException on it. The service reads such a code itself, so a bad configuration ends up as "not configured" with a hint.
Logging out an anonymous user, which is who uses a device without sign-in, fails in RevenueCat with code 22. The app counts it as done.

The tests of the modules run purchases_flutter over a stand-in for its platform side, which can't show whether premium access really reaches a running app. So CI checks that as well. It starts the app with every module on an Android emulator and an iOS simulator, with the Test Store key of a RevenueCat project. The app asks CI for premium access, a test grants the entitlement in that project through RevenueCat's REST API, with a secret key that never goes near the app, and the app has to show premium access that ends when the grant does. In the first runs, the whole exchange took 7 to 16 seconds.

Eighteen roles and twenty-five modules, checked in running apps

0.6 had sixteen roles and twenty-two modules. 0.7 has eighteen and twenty-five. The new roles are the purchases and the values in .env. The new modules are dart_define, revenuecat and paywall.

When I wrote this, CI generated 84 apps from the modules of the CLI and ran flutter analyze and flutter test in each. It also starts the apps with every module on an Android emulator and an iOS simulator, and grants them premium access in RevenueCat.

What SMF 0.7 can't do yet

There are no dev and prod environments and no HTTP client yet.
Firebase is the only provider of sign-in, analytics and crash reporting.

Where it's going

Next on my list is what an app needs before it goes to the stores: dev and prod environments, an HTTP client whose address comes from the environment, CI for the generated app, and an app icon and a splash screen. There are no dates. SMF is a side project, and I'd rather ship things when they work.

If you have a module in mind, tell me which one on Discord or in GitHub Issues.

Upgrading from 0.6

In an app with a router, firebase_analytics turns off the screen views that Firebase logs by itself, so each screen is logged once and the app logs no MainActivity or FlutterViewController. A reader of the post about screen tracking with go_router pointed this out.
The README of every generated app says that Say My Frame generated it.
The module API of smf_contracts changed: the action of an onboarding step gets the BuildContext of the onboarding, steps have a new stage offer, and a provider of the app entry has a socket for .gitignore. A module that adds onboarding steps or provides the app entry needs an update.
Apps generated by 0.6 stay as they are.

The full list is in the release notes of SMF 0.7.0 on GitHub.

Try the Flutter paywall with smf create

dart pub global activate smf_flutter_cli
smf create

SMF generates Android and iOS apps for Flutter 3.44 or newer and Dart 3.12 or newer, and it is tested on macOS, Linux and Windows. The documentation starts with installation and your first app, the paywall page covers the screens and the store rules, and the code is on GitHub. Stars there are welcome, but only if you actually like it.

Flutter Firebase Analytics screen tracking with go_router

Yevhen Beshkarov — Sat, 24 Oct 2026 00:00:00 +0000

The usual advice for Flutter Firebase Analytics screen tracking is to give FirebaseAnalyticsObserver to GoRouter. In an app with tabs, it misses screens. Going back to a tab the user has already opened logs nothing, and neither does closing a page that was opened over the tabs. A go() to a nested route logs every parent page as well, under names like b and c. I checked this on go_router 18.1.1 and firebase_analytics 13.0.0, with Flutter 3.44.2 and 3.47.4. A listener on the router delegate logs one screen view for each screen the user sees, in about 30 lines.

What FirebaseAnalyticsObserver logs with go_router tabs

The usual setup:

final router = GoRouter(
  observers: [FirebaseAnalyticsObserver(analytics: FirebaseAnalytics.instance)],
  routes: [...],
);

My test app has two tabs in a StatefulShellRoute: /home, which has a child route details, and /settings. It also has a /profile page that opens over the tabs on the root navigator, a nested route /a/b/c, and /item/:id, which is named item. A fake FirebaseAnalytics recorded every call to logScreenView:

What the user does	What the observer logs	What it should log
The app starts on Home	`/home`	`/home`
Opens the Settings tab for the first time	`/settings`	`/settings`
Goes back to the Home tab	nothing	`/home`
Opens the Settings tab again	nothing	`/settings`
`go('/home/details')`	`details`	`/home/details`
Goes back to Home	`/home`	`/home`
`push('/profile')` over the tabs	`/profile`	`/profile`
Goes back from Profile	nothing	`/home`
`go('/a/b/c')`	`/a`, `b`, `c`	`/a/b/c`
`go('/item/42')`	`item`	`item`

Users move between tabs all the time, so the reports undercount the screens behind the tabs. They also count parent pages that nobody saw.

Why FirebaseAnalyticsObserver misses tab switches

FirebaseAnalyticsObserver is a NavigatorObserver. It logs a screen view when a navigator pushes, replaces or pops a route, and at no other time. Each branch of a StatefulShellRoute has a navigator of its own, and that navigator stays alive in an IndexedStack while the user is on another tab. The first visit to a tab builds its navigator, which pushes the first page, so that visit is logged. Going back to the tab only changes which navigator is visible. No navigator pushes or pops anything.

Closing /profile pops it from the root navigator, and the observer then logs the route below it. That route is the page of the shell route. go_router names a page after the name of its route, or after its path when there is no name. A shell route has neither, so the observer gets null as the name and logs nothing.

The same goes for a page that your own pageBuilder returns. Tabs often use NoTransitionPage(child: ...), and that page has no name unless you pass one. With such a page on the Home tab, the observer never logged Home, not even when the app started. Pass name: state.name ?? state.path to the page, and it is logged like the others.

go('/a/b/c') builds the whole chain. go_router puts a page on the navigator for each of /a, b and c, so that back works, and the navigator reports a push for each of them. The names come from path, and the path of a child route is its own segment, not the full location. That is also why details lost its /home/.

Don't add an observer to each branch

Before go_router 17.0.0, the observers of GoRouter didn't hear the navigators of shell routes, so guides from that time give each ShellRoute or StatefulShellBranch observers of its own. Since 17.0.0, shell routes pass their navigation to the observers of GoRouter by default, through notifyRootObserver. With one observer on GoRouter and another on each branch, every screen in a tab is logged twice. Opening the app on Home and then the Settings tab logged this:

/home, /home, /settings, /settings

Keep only the observer on GoRouter, or pass notifyRootObserver: false to the shell route.

Log screen views from the go_router delegate

The router knows what the user sees, whichever navigator it is in. GoRouter.routerDelegate notifies its listeners each time its configuration changes, and switching tabs counts. Its currentConfiguration ends with the page on top. This listener logs that page:

import 'package:firebase_analytics/firebase_analytics.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart';
import 'package:go_router/go_router.dart';

/// Logs a screen view each time the user sees another screen: another
/// page on top of any navigator of the router, or the same page at
/// another path.
void trackScreenViews(GoRouter router, FirebaseAnalytics analytics) {
  (LocalKey, String)? last;
  router.routerDelegate.addListener(() {
    final pages = router.routerDelegate.currentConfiguration;
    final top = pages.lastOrNull;
    final shown = switch (top) {
      ImperativeRouteMatch(:final matches) => matches, // a pushed page
      _ => pages,
    };
    if (top == null || shown.isError) {
      // The error screen. Its location can hold anything, such as a token.
      last = null;
      return;
    }
    final screen = (top.pageKey, shown.uri.path);
    if (screen == last) return;
    last = screen;
    final name = top.route.name ?? shown.fullPath;
    analytics.logScreenView(screenName: name).catchError(
      (Object error) => debugPrint('Screen view not logged: $error'),
      test: (error) => error is PlatformException,
    );
  });
}

Call it once, right after you create the router, and leave out observers:

final router = GoRouter(routes: [...]);
trackScreenViews(router, FirebaseAnalytics.instance);

The same steps with the listener:

What the user does	What the listener logs
The app starts on Home	`/home`
Opens the Settings tab, then Home, then Settings	`/settings`, `/home`, `/settings`
`go('/home/details')`, then goes back	`/home/details`, `/home`
`push('/profile')`, then goes back	`/profile`, `/home`
`go('/a/b/c')`	`/a/b/c`
`go('/item/42')`, then `go('/item/43')`	`item`, `item`
`go('/home?tab=2')` while on Home	nothing

Screen names, duplicates and the error screen

The listener compares the page on top and its path with the last ones it logged. A pushed page gets a page key of its own, so pushing the same location twice logs it twice: the user saw it twice. /item/42 and /item/43 share a page key in go_router, and the path tells them apart. A change of the query alone, such as a filter, logs nothing.

A screen is named after its route, or after the full path pattern, such as /item/:id, when the route has no name. The location itself would make every item a screen of its own in the reports, and a location can hold an email address or a token. Since the listener reads routes rather than pages, a page from a pageBuilder needs no name.

When no route matches, the configuration is an error, and the location that failed can hold anything. The listener logs nothing for the error screen and forgets the last screen, so the screen the user goes back to is logged again.

Nothing waits for logScreenView, so a PlatformException would go to the handler of uncaught errors. The listener prints it instead, as FirebaseAnalyticsObserver does.

Update: Firebase Analytics logs screen views of its own

Added on 25 October 2026. After this article went out, Ahmed ZNOUDA pointed out two more things that skew screen counts in a comment below, and asked about redirects. Thanks, Ahmed.

Turn off automatic screen reporting

Firebase Analytics also logs screen views by itself. They name the activity or the view controller rather than a screen, and a Flutter app has one of each: MainActivity on Android and FlutterViewController on iOS. I ran a test app with the debug logging of Firebase Analytics on an Android 12 emulator and an iOS simulator (firebase_analytics 12.6.1). On both, every cold start logged one of these views with no screen name, right before the listener's home.home. On Android, the app logged another one each time it came back from the background. With the listener in place, turn them off. On Android, inside <application> of android/app/src/main/AndroidManifest.xml:

<meta-data
    android:name="google_analytics_automatic_screen_reporting_enabled"
    android:value="false" />

On iOS, in the top-level dictionary of ios/Runner/Info.plist:

<key>FirebaseAutomaticScreenReportingEnabled</key>
<false/>

With both keys, the same runs logged only the listener's screen view at the start, and no screen view when the app came back from the background.

Bottom sheets and dialogs

showModalBottomSheet and showDialog push a route without a page. The configuration of the router stays the same, so the listener logs nothing when the sheet opens, and nothing for the page below when it closes. FirebaseAnalyticsObserver leaves them out too, because by default it only logs a PageRoute. If a sheet is a screen you want in the reports, such as a paywall or a consent sheet, log it yourself when you show it:

FirebaseAnalytics.instance.logScreenView(screenName: 'paywall_sheet');
await showModalBottomSheet<void>(context: context, builder: buildPaywall);

Redirects

Redirects don't let a screen slip through. go_router runs redirect while it parses a location, before the delegate gets the new configuration. I checked it on go_router 18.1.1: an app that starts at /home with an auth redirect to /login logs only /login. Signing in then logs /home once, and signing out logs /login once.

How SMF does Flutter Firebase Analytics screen tracking

I ran into this while building SMF, a free, open-source Flutter project generator. In every app with go_router and the Firebase Analytics module, the router tells listeners about each screen the user sees, and the module logs a screen view for each one, with no code in the app. Tests that run in the generated apps check that listeners hear about each screen once, tab switches included.

Firebase has a trap on iOS too, in the build phase that uploads symbols to Crashlytics: how to fix the flutterfire upload-crashlytics-symbols error.

SMF 0.6: Flutter push notifications and social sign-in

Yevhen Beshkarov — Tue, 20 Oct 2026 00:00:00 +0000

Say My Frame (SMF) generates Flutter apps from independent modules. Version 0.6 is out on pub.dev. It adds Flutter push notifications with Firebase Cloud Messaging, local notifications, and sign-in with Google and Apple. At the end of the post about 0.5 these were next on my list. Some of the setup lives in the Apple Developer account and the Firebase console, where no command can reach, so 0.6 also comes with a guide for those steps, click by click.

dart pub global activate smf_flutter_cli
smf create my_app -m home,onboarding,sign_in,google_sign_in,apple_sign_in,firebase_messaging,bottom_tabs,material_theme,gen_l10n,get_it,bloc

The recording answers the questions of smf create instead of passing -m. It picks local notifications and leaves push messages out, so the app needs no APNs key. Either way, SMF adds what the chosen modules need and says why.

As before, what you get is a regular Flutter project. It has no SMF package in its dependencies, and SMF never touches it again.

Flutter push notifications and local notifications after smf create

Two new modules handle notifications, each for a role of its own:

local_notifications shows a notification now or at about a time to come, on flutter_local_notifications. It tells the app of each tap, including the tap that launched the app.
firebase_messaging gives the app the address of the device for its backend, which is the registration token of Firebase Cloud Messaging. It also gives the app the push messages that arrive there and the taps on them. A message that arrives while the app is open shows as a notification too.

Push messages lean on the notifications for the permission and for showing a message while the app is open, so firebase_messaging brings local_notifications with it. An app can have local notifications without push messages, and then it needs no Firebase project.

The app asks for nothing when it starts. In an app with an onboarding, one page of it asks for the permission to show notifications. The settings screen gets a row that shows On or Off, asks while the app hasn't asked yet, and opens the settings of the system after that. On Android 12 and older, where apps get the permission without asking, the onboarding skips that page.

The notifications guide shows how code schedules a notification, reads the address and listens to messages and taps.

Sign-in with Google and Apple in Flutter

google_sign_in adds sign-in with a Google account on Android and iOS, and apple_sign_in adds Sign in with Apple on iOS, so on Android its button doesn't show. The sign-in screen of sign_in shows "Continue with Google" and "Continue with Apple" above the form with the email address, in the theme and in both languages of the app. Firebase Authentication signs the user in with these credentials, links them to an account, and deletes such an account.

Two rules of the App Store shaped this:

An iOS app with Google sign-in also needs a way to sign in that the App Store takes as its equivalent, such as Sign in with Apple (Guideline 4.8). smf create warns of an app with Google and without Apple.
An app with Sign in with Apple revokes the tokens of Apple when the user deletes the account (Guideline 5.1.1(v)). The generated app asks Apple again before the deletion, and Firebase revokes the tokens.

After flutterfire configure, smf create offers to run a script that enables Google in the Firebase project, registers the SHA-1 and SHA-256 of your debug key and writes the URL scheme of the iOS app. Apple has no such command. The sign-in guide covers both ways to sign in.

The steps you do by hand, click by click

Some setup can't be done from a terminal:

the App ID of a paid Apple team, which push messages and Sign in with Apple need, since a free team can't sign the app with them;
the APNs key that Firebase needs to send messages to iPhones;
the Apple provider and its key in Firebase;
the SHA of your release keys;
Google Analytics in the Firebase project.

I checked for APIs before writing a guide. Firebase takes an APNs key only in its console, and the API of App Store Connect can't create such a key either.

So smf create ends with one line that says how many steps your app needs, and one link:

Finish the setup by hand in 5 steps:
  https://doc.saymyframe.com/setup?steps=app_entry.ios_app_id,firebase_auth.apple_provider,firebase_auth.apple_revocation,firebase_auth.google_release_sha,firebase_messaging.apns_key

The page behind the link shows only those steps, in their order, with screenshots of the Apple Developer account, the Firebase console and Xcode. Each step has a checkbox, so you can come back later and see where you stopped. The README of the app lists the same steps in its section "Finish the setup". In terminals that support it, the link is clickable.

What Firebase Cloud Messaging and Apple did on real devices

The tests of the modules run the real Firebase packages over a stand-in for their platform side. Before the release I went through push messages, notifications and sign-in by hand on an iPhone simulator, on Android emulators with Android 12 and 17, and against a real Firebase project. A few things there were not what I expected:

On the first start, the iPhone simulator had no address for about 13 seconds. The app picks it up when it arrives, so code that sends the address to a backend listens for it instead of reading it once.
An Android emulator that I restored from a snapshot received no messages at all until a cold boot. Nothing was wrong with the app.
On iOS, firebase_messaging also answers when a local notification is about to show. Unless the app sets the options of foreground notifications, that answer hides the notification while the app is open. The generated service sets them, so a notification shows once.
Deleting an account that signed in with Apple, before the key of Apple was in Firebase, failed with "Code flow is not enabled for Apple". The generated app tells the user that this is not available, keeps the account, and shows you the fix in debug mode. With the key in place, the account was deleted.

One more problem broke every release build on Android, and it had nothing to do with notifications. shared_preferences_android 2.5.0 came out during this work, and with it a release build crashed before its first frame. I wrote a separate post about that crash. Since then, CI also starts a release build on an Android emulator.

Sixteen roles and twenty-two modules, checked in running apps

0.5 had thirteen roles and eighteen modules. 0.6 has sixteen and twenty-two. The new roles are the notifications, the push messages and the onboarding screen, which lets modules add pages such as the one that asks for the permission. The new modules are local_notifications, firebase_messaging, google_sign_in and apple_sign_in.

When I wrote this, CI generated 59 apps from the modules of the CLI and ran flutter analyze and flutter test in each. It also configures the app with every module for a real Firebase project and starts it on an Android emulator and on an iOS simulator.

What SMF 0.6 can't do yet

Firebase is the only provider of push messages and of sign-in.
There is no networking and no in-app purchases yet.

Where it's going

Subscriptions with a paywall are next on my list. There are no dates. SMF is a side project, and I'd rather ship things when they work.

If you have a module in mind, tell me which one on Discord or in GitHub Issues.

Upgrading from 0.5

--strict now stops on a warning about what the app is made of, such as a destination in an app without a main navigation. Each such warning has a code.
firebase_auth needs the Firebase CLI 15.34.0 or newer. That version no longer adds a web app to a Firebase project that already has apps.
An app gets the fallback start screen only when no route can start it.
The module API of smf_contracts changed: modules can add code to the AppDelegate, entitlements, ways to sign in and steps by hand. A module written for 0.5 needs an update.
Apps generated by 0.5 stay as they are.

The full list is in the release notes of SMF 0.6.0 on GitHub.

Try Flutter push notifications with smf create

dart pub global activate smf_flutter_cli
smf create

SMF generates Android and iOS apps for Flutter 3.44 or newer and Dart 3.12 or newer, and it is tested on macOS, Linux and Windows. The documentation starts with installation and your first app, the notifications guide goes from the permission to push messages, and the code is on GitHub. Stars there are welcome, but only if you actually like it.

Fix shared_preferences crashing Flutter release builds

Yevhen Beshkarov — Sun, 18 Oct 2026 00:00:00 +0000

Update, 22 October 2026: the bug is fixed in shared_preferences_android 2.5.2. If you added the pin or the keep rules from the workarounds below, remove them. Then run flutter pub upgrade shared_preferences_android and check that pubspec.lock has 2.5.2.

On 17 October 2026, shared_preferences_android 2.5.0 came out, and Flutter apps that use shared_preferences stopped starting in Android release builds. The app stays on the splash screen, and logcat has a NoSuchMethodError. Debug and profile builds work, and so does iOS, so a CI that builds only debug stays green. This shared_preferences release build crash comes from R8, which renames Kotlin classes that the new version looks up by name. The fix is out in shared_preferences_android 2.5.2, so upgrade the package. If you can't upgrade yet, go back to the previous version or add six keep rules to the app.

NoSuchMethodError in SharedPreferencesAsyncApiRegistrar.getAll

With SharedPreferencesAsync or SharedPreferencesWithCache, the first call to the preferences throws:

E flutter: Unhandled Exception: PlatformException(PlatformException, java.lang.NoSuchMethodError: no non-static method "Lio/flutter/plugins/sharedpreferences/SharedPreferencesAsyncApiRegistrar;.getAll(Ljava/util/List;Lio/flutter/plugins/sharedpreferences/SharedPreferencesPigeonOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;"

With the legacy SharedPreferences.getInstance(), the class in the message is SharedPreferencesApiRegistrar:

PlatformException(PlatformException, java.lang.NoSuchMethodError: no non-static method "Lio/flutter/plugins/sharedpreferences/SharedPreferencesApiRegistrar;.getAll(Ljava/lang/String;Ljava/util/List;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;"

When the app opens the preferences in main(), before runApp(), the future fails and runApp() never runs. The app keeps showing its splash screen, and no crash dialog comes up. An app that opens the preferences later fails on the screen that reads them.

When it fails: shared_preferences_android 2.5.0 and R8

Check which version pub resolved, in the directory of the app:

flutter pub deps | grep shared_preferences_android

You have this case when:

it prints shared_preferences_android 2.5.0 or 2.5.1. shared_preferences 2.5.5 allows any 2.x of its Android side from 2.3.4 on, so a flutter pub upgrade, or a first flutter pub get between 17 and 22 October, brought one of them in. 2.5.1 only updated a dependency and has the same bug;
you build for Android in release: flutter build apk, flutter build appbundle or flutter run --release. Flutter turns R8 on for every release build, and the app bundle that you upload to Google Play has the bug too;
debug and profile builds of the same app work.

iOS and macOS use shared_preferences_foundation, and the other platforms have packages of their own, so only Android is affected.

The fix: upgrade to shared_preferences_android 2.5.2

shared_preferences_android 2.5.2 came out on 22 October. It ships consumer rules for R8, which keep the Kotlin classes in every app that uses the plugin. Upgrade it in the directory of the app:

flutter pub upgrade shared_preferences_android

If you added one of the workarounds below, take it out first: remove the dependency on shared_preferences_android before the upgrade, or delete the six rules from android/app/proguard-rules.pro, where they do no harm if you leave them. Then check that flutter pub deps | grep shared_preferences_android prints 2.5.2, and start the release build again with flutter run --release.

Workaround 1: keep shared_preferences_android below 2.5.0

flutter pub add 'shared_preferences_android:>=2.4.28 <2.5.0'

The app then depends on the Android side of the package directly, and pub goes back to 2.4.28, which talks to Kotlin through a method channel as before. The rest of the app stays as it is.

To move to 2.5.2 later, remove the dependency and upgrade the package. Without the upgrade, pubspec.lock keeps 2.4.28:

flutter pub remove shared_preferences_android
flutter pub upgrade shared_preferences_android

Workaround 2: keep the Kotlin classes with R8 rules

To stay on 2.5.0 or 2.5.1, tell R8 to keep the classes. Put these lines into android/app/proguard-rules.pro, and create the file if the app has none:

-keep class kotlin.Unit { *; }
-keep class kotlin.Result { *; }
-keep class kotlin.Result$Failure { *; }
-keep class kotlin.coroutines.Continuation { *; }
-keep class kotlin.coroutines.intrinsics.CoroutineSingletons { *; }
-keep class kotlin.coroutines.intrinsics.IntrinsicsKt { *; }

The Gradle plugin of Flutter adds this file to the release build when it exists, so build.gradle.kts stays as it is. The rules are those of Step 5 in the native interop guide of Pigeon, the tool that generates the code of the plugin.

After either workaround, start the release build again with flutter run --release.

Why the shared_preferences release build crash happens

Version 2.5.0 moved the plugin from method channels to the native interop of Pigeon (flutter/packages#12329). The Dart code now calls the Kotlin code of the plugin through JNI, and JNI finds classes and methods at run time by their names and descriptors.

R8 renames the classes that, as far as it can see, nothing refers to by name. The generated Kotlin classes of the plugin have @Keep since flutter/packages#13151, so SharedPreferencesAsyncApiRegistrar keeps its name. Its methods are suspend functions, though, and their last parameter is a kotlin.coroutines.Continuation. Nothing keeps that class. From build/app/outputs/mapping/release/mapping.txt of a release build:

kotlin.coroutines.Continuation -> o1.d:

R8 renames the class and rewrites the descriptor of getAll with the new name. The Dart side still asks for a method that ends with Lkotlin/coroutines/Continuation;, and that method no longer exists. The same goes for kotlin.Unit, kotlin.Result and the coroutine classes that package:jni 1.1.0 looks up by name in lib/src/kotlin.dart. The plugin has no consumer rules for R8, and the rules of jni keep only its own package, com.github.dart_lang.jni.**.

Debug and profile builds run without R8, so every name stays and the calls work.

Why a green CI with debug builds missed it

The release APK builds without an error and fails only when its code runs. I found it by chance on the day 2.5.0 came out: while checking an unrelated change in SMF, I started a release build on an emulator, and it stayed on the splash screen. An app from a plain flutter create did the same. The CI of SMF builds its generated apps for Android and starts them on an emulator, on every pull request and every night, and every Android build there was a debug build. So it stayed green.

Your users get a release build, so start one before they do: once a day in CI, or by hand before each release. Build it with flutter build apk --release, install it on an emulator and check that the first screen shows. R8 runs only in release builds, and that is the only place where a bug like this one shows up.

The upstream fix

flutter/flutter#194649 is the issue I opened on 17 October, with the steps to reproduce. Within a day, other apps linked to it from their own fixes.
flutter/packages#13311 is my pull request. It adds the six rules to shared_preferences_android as consumer rules, which R8 applies in every app that uses the plugin. It was merged on 21 October and came out in 2.5.2 a day later, since an outage of the CI of Flutter stopped the first release run.
dart-lang/native#3732 is about shipping the rules in jni itself, so that every plugin on the native interop of Pigeon gets them.

If another plugin of your app moves to the native interop of Pigeon and its release build fails with a NoSuchMethodError or a ClassNotFoundException that names a kotlin class, try the same rules first.

How SMF keeps generated apps on shared_preferences_android 2.4.28

I ran into this while building SMF, a free, open-source Flutter project generator. Since version 0.4.2, released on 17 October, its shared_preferences module keeps shared_preferences_android below 2.5.0 in every app it generates. The guide for coding agents in the app says why, and asks them to start a release build on Android before they raise the constraint. The CI of SMF now also starts a release build of a generated app on an Android emulator.

On iOS I hit the same kind of trap, where debug works and the release archive fails: the Crashlytics build phase of FlutterFire breaks flutter build ipa in apps with Swift Package Manager. The fix for the flutterfire upload-crashlytics-symbols error is in an earlier post.

SMF 0.5: Flutter sign-in with Firebase Authentication

Yevhen Beshkarov — Mon, 12 Oct 2026 00:00:00 +0000

Say My Frame (SMF) generates Flutter apps from independent modules. Version 0.5 is out on pub.dev, and it brings Flutter sign-in. An app you generate can now have screens where a user signs in with an email address and a password, creates an account or resets a password. It also gets an account screen, and Firebase Authentication keeps the accounts. The post about 0.4 ended with sign-in as the next thing on my list. This one is about what you get, what it needs from you, and what it still can't do.

dart pub global activate smf_flutter_cli
smf create my_app -m home,onboarding,sign_in,bloc,bottom_tabs,gen_l10n,material_theme

The recording answers the questions of smf create instead of passing -m, and it also picks get_it. Either way, SMF adds what the chosen modules need and says why: sign_in brings firebase_auth, firebase_core and settings with it.

The home page of Say My Frame has a video of a walk through this app, with a sign-up.

An app with sign_in needs a Firebase project. smf create offers to run flutterfire configure once the app is generated. Until that command has run, the app compiles but stops at start-up with an UnsupportedError, because its Firebase options are still a placeholder.

As before, what you get is a regular Flutter project. It has no SMF package in its dependencies, and SMF never touches it again.

What Flutter sign-in looks like after smf create

Sign-in, sign-up, password reset and an account screen

The module sign_in adds four screens. On three of them a user signs in, creates an account, or asks for the message that resets a password. The password reset says the same whether the address has an account or not. The fourth is the account screen, where the user signs out or deletes the account after a confirmation, and the settings screen gets a row that leads to it.

The screens take their fields, buttons and colors from the theme of the app, and their texts are in English and Ukrainian. Every reason of a failure has a text of its own, such as a wrong password or no connection. As with the onboarding in 0.4, the tests put the screens on a phone of 320 by 480 with the text at three times its size. The page of the sign-in module shows each screen.

One question: who may use the app without an account

In an app with sign-in, smf create asks one new question:

? Who may use the app without an account? (↑↓ to move, enter to choose)
❯ Nobody: the user signs in first
  Everyone: an account only where a screen needs one
  Everyone, as an anonymous user with an id from the start

--auth-mode answers it in advance with required, guest or anonymous.

With the first answer, the sign-in shows in place of every screen until the user is signed in.
With the second, the app is open. When the user asks for a screen that needs an account, such as the account screen, the sign-in opens over the page they are on. Back returns to that page, and after the sign-in the app shows the screen that was asked for.
The third works the same way, and the app also signs in an anonymous user when it starts, so your code has the id of a user before anyone has an account. Signing up gives that user the account, with the same id.

The code of the screens is the same in all three, and the answer is one constant in lib/core/auth/app_session.dart. The sign-in guide describes the modes and how a screen of your own asks for an account.

The screens change the session, and the router does the rest

No screen of sign_in closes itself or navigates after a sign-in or a sign-out. The module declares two guards of the routes, and the router of the app shows the sign-in and takes it away by what they say. The route of the account screen asks for a condition:

Route(
  '/account',
  name: 'account',
  screen: ScreenRef(
    'AccountScreen',
    import: ImportRef.app('$_folder/account_screen.dart'),
  ),
  conditions: [AuthRole.account],
),

The authentication role publishes AuthRole.account, and sign_in stands for it with a guard. A feature of your own that asks for the same condition gets the same guard without naming sign_in. The module never mentions go_router either.

The router role had to learn two things for this. The flow of a guard now closes itself: once the user is signed in, the router takes the sign-in away. And a route can ask for a condition, which opens the sign-in over the screen the user is on and brings the user back. Guards of routes and conditions of routes have the rules.

BLoC or Riverpod over one look

sign_in is the first module of SMF with a variant for each state manager. The views, the forms and the texts are the same files in both. With bloc, each screen has a cubit, and with riverpod, a provider that lasts as long as the screen. Either way the state signs in through appSession, the session of the app, and knows nothing of Firebase.

Firebase Authentication behind a role

sign_in keeps no accounts. It requires the authentication role, and the module firebase_auth provides that role with Firebase Authentication.

A Firebase project needs one more thing than flutterfire configure: the ways to sign in are enabled in the project, not in the code. The module generates a script of the app that enables them with the Firebase CLI, 15.6.0 or later, and smf create offers to run it right after the configuration:

dart tool/enable_firebase_sign_in.dart

It asks first, because the Firebase CLI adds a web app named "Default Web App" to a project that has none. The Firebase console enables the same methods without it. If you answer no, or the run has no terminal, nothing went wrong, so the run doesn't warn. It lists the steps that are left, in the order to run them, after it says that the app is created. The Firebase guide has the details.

What Firebase Authentication answers on a real device

The service that talks to Firebase had tests before it met a device. They run the real firebase_auth package over a stand-in for its platform side, and they passed. Before I merged the module, I ran the same calls by hand on an Android emulator and an iPhone simulator, against a project with sign-in enabled and against one where Authentication had never been opened. The devices answered in ways the stand-in knew nothing about:

In a project without Authentication, Android answers with an unknown error that has CONFIGURATION_NOT_FOUND in its message. iOS answers with an internal error whose message is the description of the error over many lines.
Android refuses an empty password with a code that says nothing of the reason. iOS answers that the password is wrong.
An anonymous user that Android kept on the device comes back with an empty email address instead of no address.

The generated service evens these out, so a screen shows the same text on both platforms. It checks an empty field before it asks Firebase, takes an empty address for none, and gives each code of Firebase one of ten reasons that the screens have a text for. When sign-in is not enabled in the project, the user reads only that sign-in is unavailable, and in debug mode the screen adds a hint for you, with the command and the link that fix it. The page of the firebase_auth module lists every code.

Thirteen roles and eighteen modules, checked in running apps

0.4 had twelve roles and sixteen modules. 0.5 has thirteen and eighteen: the new role is authentication, and the new modules are sign_in and firebase_auth.

When I wrote this, CI generated 46 apps from the modules of the CLI and ran flutter analyze and flutter test in each. The tests of sign-in run in each of the three modes. CI also configures the app with every module for a real Firebase project, enables its sign-in methods there with the script, and starts the app on an Android emulator and on an iOS simulator.

What SMF 0.5 can't do yet

Sign-in is with an email address and a password. There is no sign-in with Google or Apple yet.
Firebase Authentication is the only provider of the role, so an app with sign_in needs a Firebase project and does not start until flutterfire configure has run.
The app doesn't ask a new user to confirm the email address, and it has no screen that changes the address or the password.
Firebase may refuse to delete an account whose user signed in long ago. The screen then tells the user to sign out and sign in again.
A screen that needs an account can't be a tab of the main navigation or the screen the app starts on.
There is still no networking and no push notifications, and SMF still can't add a module to an app you already have.
It generates Android and iOS apps for Flutter 3.44 or newer and Dart 3.12 or newer.

Where it's going

Sign-in with Google and Apple and push notifications are next on my list. Adding modules to an app that already exists is still on it too. There are no dates. SMF is a side project, and I'd rather ship things when they work.

If you have a module in mind, tell me which one on Discord or in GitHub Issues.

Upgrading from 0.4

No option of smf create changed or went away. --auth-mode is new.
A step that you leave for later, such as flutterfire configure, is no longer a warning. The run lists it after it says that the app is created.
In an app without a main navigation, smf create now warns of each destination that no screen leads to.
The module API of smf_contracts changed: a guard now names its stage, and a module that provides the router role handles new answers of the guards. A module written for 0.4 needs an update.
Apps generated by 0.4 stay as they are.

The full list is in the release notes of SMF 0.5.0 on GitHub.

Try Flutter sign-in with smf create

dart pub global activate smf_flutter_cli
smf create

SMF is tested on macOS, Linux and Windows. The documentation starts with installation and your first app, the sign-in guide goes from the screens to the Firebase project, and the code is on GitHub. Stars there are welcome, but only if you actually like it.

Fix the flutterfire upload-crashlytics-symbols error

Yevhen Beshkarov — Wed, 07 Oct 2026 00:00:00 +0000

flutter run works, flutter build ios works, and then flutter build ipa fails in the build phase that the FlutterFire CLI adds for Firebase Crashlytics. This flutterfire upload-crashlytics-symbols error says that the upload script of Crashlytics is missing. The script is on the disk, but when Xcode archives an app that uses Swift Package Manager, the phase looks for it in the wrong directory. The fix changes one path in the Xcode project, and you have to apply it again after every flutterfire configure.

"Could not find the Crashlytics upload symbols script" in flutter build ipa

The phase named FlutterFire: "flutterfire upload-crashlytics-symbols" uploads the dSYM files of the iOS app to Firebase Crashlytics. With Swift Package Manager, the archive stops in it:

Unhandled exception:
Exception: Could not find the Crashlytics upload symbols script at "/Users/<you>/Library/Developer/Xcode/DerivedData/Runner-<hash>/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run". This usually means CocoaPods or Swift Package Manager has not finished installing "FirebaseCrashlytics" yet, or it was installed to an unexpected location. Try cleaning and rebuilding the project.
#0 UploadCrashlyticsSymbols.run (package:flutterfire_cli/src/commands/upload_symbols.dart:368:7)
Command PhaseScriptExecution failed with a nonzero exit code

**ARCHIVE FAILED**

I got it with flutterfire_cli 1.4.1, the latest version when I wrote this, Flutter 3.44.2 and Xcode 27. The message suggests cleaning and rebuilding. Flutter 3.44 keeps the Swift packages somewhere else, so the script will not turn up in DerivedData however often you clean.

When it fails: flutter build ipa, but not flutter run

You have this case when:

the Firebase packages of the app come through Swift Package Manager, which Flutter 3.44 uses by default, and not through CocoaPods;
flutterfire_cli 1.4.1 configured the app on a Mac (it adds the phase only on macOS);
flutter run and flutter build ios succeed, and the phase uploads the symbols;
flutter build ipa fails. A comment in the upstream issue reports the same for Product > Archive in Xcode.

If flutter run fails too, with ProcessException: No such file or directory, an older flutterfire_cli wrote the phase. That case has its own section below.

The fix for the flutterfire upload-crashlytics-symbols error

The phase has the path $BUILD_DIR/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run twice. Replace both with $SRCROOT/../build/ios/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run. In the directory of the app:

ruby -e 'f = ARGV[0]; s = File.exist?(f) ? File.binread(f) : ""; t = s.gsub("$BUILD_DIR/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run", "$SRCROOT/../build/ios/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"); if t == s then puts "Nothing to fix in #{f}" else File.binwrite(f, t); puts "Fixed the Crashlytics phase in #{f}" end' ios/Runner.xcodeproj/project.pbxproj

It prints Fixed the Crashlytics phase in ios/Runner.xcodeproj/project.pbxproj, or Nothing to fix in ios/Runner.xcodeproj/project.pbxproj when the file has no such path, for example because you fixed it already. Nothing else in the project changes. You can make the same edit by hand in Xcode: the Runner target, Build Phases, the phase with the name above.

After that, flutter build ipa archives the app and the phase uploads the symbols. flutter run and flutter build ios work as before, because for them both paths are the same directory.

Two caveats:

flutterfire configure writes the phase again when its script differs from the one it would write. Run the fix after every flutterfire configure.
The new path assumes that Flutter builds into build. If you changed that with flutter config --build-dir, the path is wrong for you. Flutter exports FLUTTER_APPLICATION_PATH and FLUTTER_BUILD_DIR to the phase, so "${FLUTTER_APPLICATION_PATH}/${FLUTTER_BUILD_DIR}/ios/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run" should follow your setting. I have tried only the default.

Why the phase misses the Crashlytics upload script

The script of the phase looks for the upload script in four places, in this order:

$PODS_ROOT/FirebaseCrashlytics/run, for CocoaPods;
$BUILD_DIR/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run;
the same SourcePackages path in the DerivedData directory of the project;
whatever find turns up in $BUILD_DIR and in that DerivedData directory.

With Swift Package Manager, Flutter clones the packages of the app into build/ios/SourcePackages: it passes -clonedSourcePackagesDirPath to xcodebuild. For flutter run and flutter build ios it also passes BUILD_DIR=<app>/build/ios, so the second place has the script. For an archive it leaves BUILD_DIR alone, on purpose:

      if (buildAction !=
          XcodeBuildAction.archive) // dSYM files aren't copied to the archive if BUILD_DIR is set.
        'BUILD_DIR=${globals.fs.path.absolute(buildDirectoryPath)}',

So during flutter build ipa, $BUILD_DIR is the one Xcode picks:

~/Library/Developer/Xcode/DerivedData/Runner-<hash>/Build/Intermediates.noindex/ArchiveIntermediates/Runner/BuildProductsPath

None of the four places has the script. The phase hands flutterfire the DerivedData path of the third place, and that is the path in the error. The stable branch of Flutter had the same lines on the day I wrote this.

$SRCROOT is the ios directory of the app. $SRCROOT/../build/ios/SourcePackages is where Flutter put the packages, whatever $BUILD_DIR says.

ProcessException: No such file or directory with flutterfire_cli 1.4.0 or older

The phase that flutterfire_cli 1.4.0 and older versions write knows only CocoaPods and DerivedData. With Flutter 3.44 and Swift Package Manager it fails in every iOS build, flutter run included:

Unhandled exception:
ProcessException: No such file or directory
  Command:
  /Users/<you>/Library/Developer/Xcode/DerivedData/Runner-<hash>/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run --validate --flutter-project .../app_id_file.json

Activating flutterfire_cli 1.4.1 does not fix it, because the old phase stays in the Xcode project. Activate it and configure the app again on a Mac, and the new phase replaces the old one:

dart pub global activate flutterfire_cli 1.4.1
flutterfire configure

Then apply the fix above, for flutter build ipa.

Where the fix stands in flutterfire_cli

The upstream issue is invertase/flutterfire_cli#443, open since May 2026. Version 1.4.1, from August, added the lookup in $BUILD_DIR/SourcePackages, which covers flutter run and flutter build ios. The comments of the issue describe the archive case, the latest of them from the end of September. Two open pull requests change the lookup: #444 and #456. #428 is about the same phase in macOS apps, which I have not tried.

When a release with one of them is out, activate it and run flutterfire configure again. You will not need the fix from this post then.

How SMF applies the fix after flutterfire configure

I ran into this while building SMF, a free, open-source Flutter project generator. The launch post of SMF 0.3 says what it does today and what it can't do yet. For an app with Firebase Crashlytics, SMF runs this fix on macOS right after flutterfire configure, and puts the command into the README of the app for the next time you configure it yourself. Its CI archives a generated app with flutter build ipa --no-codesign and the fixed phase. Another job runs the real flutterfire configure and fails when the phase no longer has the path that the fix replaces, so a change upstream shows up as a red job. The Firebase guide of SMF has the details.

SMF 0.4: a Flutter starter app with onboarding and settings

Yevhen Beshkarov — Wed, 07 Oct 2026 00:00:00 +0000

Say My Frame (SMF) generates Flutter apps from independent modules. Version 0.4 is out on pub.dev, and what it generates now is a Flutter starter app that you can show to someone. It opens with an onboarding, greets you on a start screen that lists what to do next, and has a settings screen where the user chooses the theme and the language. The post about 0.3 said that the app you get is a skeleton. This one is about what replaced the skeleton, what is still missing, and what I plan next.

dart pub global activate smf_flutter_cli
smf create my_app -m home,onboarding,settings,bottom_tabs,material_theme,gen_l10n,get_it,bloc

The recording answers the questions of smf create instead of passing -m. Either way, SMF adds go_router and shared_preferences by itself: the start screen needs a router, and the onboarding needs a place to remember that the user has finished it.

The home page of Say My Frame has a half-minute video of a walk through this app.

0.3 put the work into the module model, and the app it generated showed none of it: after smf create you saw one screen with the name of the app. 0.4 went into the app.

As before, what you get is a regular Flutter project. It has no SMF package in its dependencies, and SMF never touches it again.

What the Flutter starter app has after smf create

A Flutter onboarding screen on the first launch

The module onboarding adds two pages that a new user goes through once. Its buttons only finish the onboarding and navigate nowhere. The module declares a guard of the routes, and the router of the app shows the onboarding in place of every other screen until the user has finished it:

guards: [
  RouteGuard(
    name: 'firstRun',
    allows: FunctionRef('onboardingCompleted', import: _status),
    redirectTo: _route,
  ),
],

Here _status is the file with that function, and _route is the route of the onboarding itself. The module never mentions go_router. Guards are part of the router role, so another router would have to ask them the same way. The app remembers that the onboarding is finished, and onboardingStatus.restart() shows it again.

The pages are a list in lib/features/onboarding/onboarding_pages.dart, and you replace them with your own:

List<Widget> onboardingPages(BuildContext context) => [
  OnboardingPage(
    symbol: 'Ma',
    title: 'My App',
    text: context.l10n.onboardingWelcome,
  ),
  OnboardingPage(
    icon: Icons.check_rounded,
    title: context.l10n.onboardingReadyTitle,
    text: context.l10n.onboardingReady,
  ),
];

The page of the onboarding module has the rest, and guards of routes explains how a module keeps the user away from a screen.

A start screen written for the developer

In 0.3 the start screen of home showed the name of the app. Now it is a welcome for you, the developer. It names the app, greets you by the time of the day and lists three next steps. Each step has the path of a file, and a tap copies it. The first step is to replace this screen with the first screen of your app, and the page of the home module shows how.

A settings screen that the modules fill

The module settings adds a settings screen and knows nothing about what is on it. Modules and roles give it entries. In an app with a theme and a localization, the screen has the theme mode (light, dark or the one of the device) and the language.

Neither entry comes from the module that provides the theme or the texts. The theme mode belongs to the theme role and the language to the localization role, so a second theme module would get the same entry without writing it. In an app whose modules have no setting, the screen shows a note for the developer instead of an empty list.

A light and a dark Material 3 theme with a bundled font

material_theme generates lib/core/theme/app_theme.dart with a palette, text styles and the look of the components. That file is yours to edit, and the theme guide says what to change and where. The font files are in assets/fonts/geist/ with their license, so the app loads no font from the network and gets no package for it.

Flutter localization in two languages with gen-l10n

gen_l10n writes the texts of the modules into ARB files, one for each language, and flutter pub get generates the class that code reads them through. The modules come with texts in English and Ukrainian. --locales chooses the languages of the app. Until the user chooses one, the app follows the device.

The theme mode and the language are remembered between launches. shared_preferences keeps them, and it is meant only for settings that are no secret. Code changes them with one call each:

await appThemeMode.choose(ThemeMode.dark);
await appLocale.choose(const Locale('uk'));

The languages guide and the preferences guide have the details.

Large text, less motion and a screen reader

I did not want screens that look right only on my phone. The tests of the onboarding and of the start screen put them on a phone of 320 by 480 with the text at three times its size, in each language of the app, and fail when something overflows. The motion of these screens ends, and an app that asks for less motion shows them at once. Titles are headers for a screen reader, and each tab of the bar at the bottom is one button for it.

A guide for coding agents in every app

Every generated app has AGENTS.md and CLAUDE.md. The guide says where the files of each role are, how code of the app uses them and what code must not do. The roles and the modules of the app write its sections, so it describes this app and not SMF in general. There is an example in the coding agents guide.

Twelve roles and sixteen modules that still don't know each other

0.3 had eight roles and eleven modules. 0.4 has twelve roles and sixteen modules. The new roles are the preferences, the settings screen, the localization and the theme, and the new modules are onboarding, settings, material_theme, gen_l10n and shared_preferences.

The rule of 0.3 held: a module names roles and never another module. A feature shows its texts through the localization role, and in an app without it the same feature shows them in English. The screens read their colors from the theme of the app, whichever module provides it, and they work in an app with no theme module too.

CI checks this by running the apps. When I wrote this, it generated 32 apps from the modules of the CLI and ran flutter analyze and flutter test in each. It also starts apps on an Android emulator and on an iOS simulator. Tests of the roles run inside the generated apps. To show that these tests can fail, the repository keeps a provider with one planted bug for each role they cover, and CI checks that the tests fail on it. Module independence in the docs describes the rules.

What SMF 0.4 can't do yet

There is no sign-in, no networking and no push notifications.
SMF creates new apps. It still can't add a module to an app you already have.
The texts of the modules are in English and Ukrainian. For another language of --locales, the app shows them in English until you translate its ARB file.
Most roles have one provider: one router, one theme, one way to keep the texts.
It generates Android and iOS apps for Flutter 3.44 or newer and Dart 3.12 or newer.

Where it's going

Sign-in is next on my list: email and password, and screens only for users who are signed in. The guards of routes that the onboarding uses were built with that in mind. Adding modules to an app that already exists is still on the list too. There are no dates. SMF is a side project, and I'd rather ship things when they work.

If you have a module in mind, tell me which one on Discord or in GitHub Issues.

Upgrading from 0.3

No option of smf create changed or went away. --locales is new.
home is a welcome with next steps now, and bottom_tabs draws its bar in the colors of the theme.
The module API of smf_contracts changed in several places, so a module written for 0.3 needs an update.
Apps generated by 0.3 stay as they are. SMF generates an app once and never touches it again.

The full list is in the release notes of SMF 0.4.0 on GitHub.

Try the Flutter starter app

dart pub global activate smf_flutter_cli
smf create

SMF is tested on macOS, Linux and Windows. The documentation starts with installation and your first app, the tour of a generated app goes through its files, and the code is on GitHub. Stars there are welcome, but only if you actually like it.

SMF 0.3: an open-source Flutter project generator

Yevhen Beshkarov — Tue, 29 Sep 2026 00:00:00 +0000

Say My Frame (SMF) is a free, open-source Flutter project generator whose modules are checked together: its CI generates apps from many combinations of them and analyzes each one. It also sets up Firebase Crashlytics and Analytics all the way to flutter build ipa. You choose what the app needs, such as go_router, tabs at the bottom, get_it, and BLoC or Riverpod, and smf create generates a Flutter project in which these parts already work together. Version 0.3 is out on pub.dev. It does less than the word "generator" might promise, so this post is about what it does today, what it can't do yet, and where I want to take it.

dart pub global activate smf_flutter_cli
smf create my_app --org com.example -m home,bottom_tabs,get_it,bloc --no-input

What you get is a regular Flutter project. It has no SMF package in its dependencies, and nothing in it has to be generated again, so the code is yours from the first commit.

Why SMF 0.3 is a rewrite

SMF 0.1 came out in August 2025, and 0.2 followed in September. Each module brought its own templates, and an engine patched the shared files. It worked for the combinations I had tried.

This September I ran the published 0.2 with Flutter 3.44. It reported success and generated apps that did not build. Some modules assumed go_router or get_it, and CI back then never generated an app or ran the analyzer, so nothing caught it.

0.3 starts from one rule: modules do not know each other.

What the Flutter project generator does today

Modules name roles, not other modules

The start screen needs a router, not go_router. The analytics module logs screen views when the app has a router, whichever router that is. SMF calls these shared parts roles, and there are eight of them: app entry, router, layout, state management, dependency injection, events, crash reporting and analytics. A role can have more than one provider. BLoC and Riverpod both provide state management.

Modules don't edit files either. Shared files, such as bootstrap.dart, have sockets: named places where modules put code without knowing who else puts code there. This is how firebase_analytics hands the router a listener of the screen, and only when the app has a router:

const SocketContribution.item(
  RouterRole.screenListeners,
  Fragment(
    'logFirebaseScreenView',
    imports: [
      ImportRef.app(
        'core/analytics/firebase_analytics_service.dart',
        show: ['logFirebaseScreenView'],
      ),
    ],
  ),
  when: {routerRole},
),

Before it writes a single file, smf create checks the rules. A module may put code only into the sockets of its own roles, of the app entry and of the modules it depends on, and every file of the app has exactly one owner. The tests of every module run the same checks. CI then generates apps from combinations of the modules, 18 of them for the modules of the CLI when I wrote this, runs flutter analyze on each one and runs tests in some of them. The module model and module independence pages of the docs go deeper.

Firebase Crashlytics and Analytics, set up all the way to `flutter build ipa`

Three modules bring Firebase: firebase_core, firebase_crashlytics and firebase_analytics. Before it generates anything, SMF checks the machine for the Firebase CLI, a Firebase login and the FlutterFire CLI. In a terminal it offers to set up what is missing, and asks first. After generation it offers to run flutterfire configure with the ids of the app.

Two details took longer than the rest. With a router, firebase_analytics logs one screen view for each screen the user sees, tab switches included. And on macOS, SMF fixes the Crashlytics build phase that flutterfire_cli 1.4.1 adds, because flutter build ipa fails in that phase when the app uses Swift Package Manager. That story gets a post of its own. Until then, the Firebase guide has the details.

A Flutter app with go_router, tabs, get_it and BLoC or Riverpod

With -m home,bottom_tabs,get_it,event_bus, SMF adds two more modules and tells you why:

Adding flutter_core: the only provider of the app entry role, which every app needs.
Adding go_router: the only provider of the router role, which home requires.

Screens navigate with context.nav.home.home().go(), which doesn't mention go_router. Code that needs a service asks the ServiceLocator of the DI role, which doesn't mention get_it. With bottom_tabs, the destinations of the features become tabs of a NavigationBar, and each tab keeps its own stack. bootstrap() runs the start-up code of the modules in four phases before the first frame. The Android and iOS projects are the ones flutter create writes in Flutter 3.44.

The tour of a generated app goes file by file and names the module that wrote each one.

A plan before anything is written

--explain prints what would be generated and stops. It lists the modules and why each is there, the roles, the dependencies, the commands that would run after generation and the state of the machine:

Modules
  home: requested
  bottom_tabs: requested
  get_it: requested
  event_bus: requested
  flutter_core: the only provider of the app entry role, which every app needs
  go_router: the only provider of the router role, which home requires

Roles
  Layout: bottom_tabs
  Dependency injection: get_it
  Events: event_bus
  App entry: flutter_core
  Router: go_router

For scripts and CI there are --no-input, --skip-external-setup, --strict and exit codes: 0, 1, 64, 70 and 130. SMF renders the app in memory and finishes it in a temporary directory, so a run that fails or that you cancel leaves no half-made app in your project. The reference of smf create lists every option.

Modules of your own

Modules are Dart packages built on smf_contracts, and yours follow the same rules as the built-in ones. The contract harness in smf_pipeline generates in memory every app that matters for your module and checks it. To generate apps with your module, you write a small command of your own with runCli and smfModules. Extending SMF shows how, and one of its pages builds a counter feature with BLoC and Riverpod variants from start to end.

What SMF 0.3 can't do yet

The app you get is a skeleton. There is one feature module, home, a start screen with the name of the app. The tab bar stays hidden until a second screen is a destination, so after smf create you see one screen.
There are no modules for sign-in, networking, localization or theming. The list has eleven modules, and I wanted the foundation to hold before adding more.
SMF creates new apps. It can't add a module to an app you already have.
It generates Android and iOS apps for Flutter 3.44 or newer and Dart 3.12 or newer.
flutterfire configure needs you at the keyboard to log in and pick a Firebase project. In CI, SMF leaves it for later and prints the command.

Where it's going

Two things are next on my list: modules with real screens, and a way to add modules to an app that already exists. There are no dates. SMF is a side project, and I'd rather ship things when they work.

If you have a module in mind, tell me which one on Discord or in GitHub Issues.

Upgrading from 0.2

The state manager is a module now: -m bloc or -m riverpod instead of -s.
--start replaces -r and --route.
--strict and --on-conflict are options of create now, so they go after it: smf create my_app --strict.
Tabs at the bottom are a module of their own, bottom_tabs.
The module API of smf_contracts is new, so modules written for 0.2 need a rewrite.
Apps generated by 0.2 stay as they are. SMF generates an app once and never touches it again.

The same list, with what's new in 0.3, is in the release notes of SMF 0.3.0 on GitHub.

Try the Flutter project generator

dart pub global activate smf_flutter_cli
smf create

SMF is tested on macOS, Linux and Windows. The documentation starts with installation and your first app, the Say My Frame site shows the roles and modules at a glance, and the code is on GitHub. Stars there are welcome, but only if you actually like it.