Skip to main content

Troubleshooting

Installing and running smf​

smf: command not found​

dart pub global activate installs smf in the directory of globally activated Dart packages, ~/.pub-cache/bin on macOS and Linux, which may not be on your PATH. Add it as the Dart documentation describes, and open a new terminal.

The Flutter SDK is missing or too old​

smf create checks the Flutter SDK before it generates anything. It uses the flutter on the PATH and the dart of the same SDK. If there is no flutter there, install Flutter and add its bin directory to the PATH.

The apps need Flutter 3.44 or newer and Dart 3.12 or newer. flutter_core sets these constraints, and every app needs it for the app entry, so with an older SDK smf create stops before it generates anything and names both versions:

Generation stopped because of 2 errors.
  error [flutter_core]: flutter_core needs Dart ^3.12.0, but the Flutter SDK at /path/to/flutter/bin/flutter has Dart 3.10.1. (Upgrade Flutter.)
  error [flutter_core]: flutter_core needs Flutter >=3.44.0, but the Flutter SDK at /path/to/flutter/bin/flutter has Flutter 3.41.0. (Upgrade Flutter.)

Upgrade Flutter, or put a newer Flutter SDK first on the PATH.

Errors of smf create​

The exit code tells what kind of problem it was.

CodeWhat to do
64The command line was wrong or incomplete. The message says what to change, and smf create --help lists the options. A run without a terminal also stops with 64 when it would have to ask, such as for the app name, for what to do with an existing directory (--on-conflict), or for which of several modules provides a role.
1Generation failed, and the messages say why. If the app was generated already, it stays in a temporary directory that the message names, so you can look at it.
70An unexpected error, which is a bug of smf or of a module. Run the same command again with --verbose for the full log, and please report it.

"Leaving out …"​

By default, smf create leaves out a module that cannot work in the app, with a warning that says why, and generates the rest. Add --strict to stop instead. A module that every app needs, such as flutter_core, is never left out: its problem stops the run. See lenient and strict.

The app's directory already exists​

In a terminal, smf create asks what to do. Without one, choose with --on-conflict: replace, copy to create the app next to it, or cancel.

Building the app​

iOS builds with Xcode 27​

Xcode 27 builds only for iOS 15 and newer, which Flutter follows from version 3.47. With Flutter 3.44 and Xcode 27:

  • flutter build ios --simulator fails in debug_unpack_ios: Flutter passes both architectures of the simulator to lipo -verify_arch, which takes one in Xcode 27. Build for the architecture of your Mac:

    FLUTTER_XCODE_ARCHS=arm64 flutter build ios --simulator

  • A plugin that installs with CocoaPods and asks for iOS 13 or 14 keeps that version, which Xcode 27 refuses. Flutter 3.47 raises it to the version of the app.

So for iOS builds with Xcode 27, use Flutter 3.47 or newer. The apps of SMF set the minimum iOS version to 15.0.

flutter analyze reports problems in build/​

On macOS, Flutter copies the Swift packages of plugins that depend on other plugins into build/ios/SourcePackages, together with their examples, which do not analyze in the app. That is why the analysis_options.yaml of a generated app leaves build/** out of the analysis. Keep that exclusion if you replace the file.

flutter analyze fails in a directory whose path has letters beyond ASCII​

With Flutter 3.44 and 3.47, flutter analyze stops with exit code 255 and a FormatException: Unterminated string from LspByteStreamServerChannel when the path of the app has a letter beyond ASCII, such as é or a Cyrillic letter. An app of flutter create in that directory fails the same way, so the cause is in Flutter, not in SMF: the tool counts the length of a message to the analysis server in UTF-16 code units instead of bytes. Flutter fixed it in its main branch (flutter/flutter#191377).

Until your Flutter has the fix, keep the app in a directory whose path has only ASCII letters, or analyze it with dart analyze, which works there and reports the same issues:

dart analyze --fatal-infos

flutter pub get and flutter test work in such a directory.

Testing the app​

A test that runs bootstrap() fails with "The SharedPreferencesAsyncPlatform instance must be set"​

The app has shared_preferences, and bootstrap() opens the preferences, which a test has no platform side for. Put the preferences of the package into memory before the test runs bootstrap() or main():

import 'package:shared_preferences_platform_interface/in_memory_shared_preferences_async.dart';
import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';

// ... and in the test, before bootstrap() or main():
SharedPreferencesAsyncPlatform.instance =
    InMemorySharedPreferencesAsync.empty();

Both names come from the package shared_preferences_platform_interface, each from a library of its own. Add the package to the app as a dev dependency with flutter pub add dev:shared_preferences_platform_interface.

A test that signs a user up before the app starts never finishes​

A call of appSession that is made before the app starts waits for the start-up. Made in the body of a widget test, it waits in the fake time of that body, and a start-up that runs in real time, as in tester.runAsync, then never completes. Make the call outside the body of a test, as in a setUpAll, and do not await it. See Sign-in.

Texts and languages​

context.l10n lacks a text that an ARB file has​

The app has gen_l10n, and gen-l10n of Flutter writes the code that reads the ARB files. Run flutter gen-l10n after every change of the files in lib/l10n, a new file included: flutter pub get generates the code in a fresh clone of the app, and does not notice a new file. The language also goes into appLocales and into the Info.plist of the iOS app; see Add a language.

Sign-in​

Signing in or signing up fails with notConfigured​

The app has firebase_auth, and the way to sign in is not enabled in the Firebase project. The screens of sign_in then say only that sign-in is unavailable, and show the developerHint of the failure below that text in a debug build. The hint tells both ways to enable it:

AuthFailure: notConfigured (Sign-in is not enabled in the Firebase project my-project (Firebase answered operation-not-allowed). To fix it, run `dart tool/enable_firebase_sign_in.dart` in the directory of the app, or enable Email/Password, and Anonymous for an app that signs in anonymous users, in the Firebase console under Authentication > Sign-in method: https://console.firebase.google.com/project/my-project/authentication/providers)

Run the script, or enable Email/Password in the Firebase console, and Anonymous for an app in the mode anonymous; see Firebase. On iOS and macOS, Firebase may answer for a project without Authentication with an internal error that says no more. The hint then says that this may be the cause, or another internal error.

In the mode anonymous, the app starts without a user​

The app signs in an anonymous user when it starts and waits for that for at most 3 seconds. When the sign-in fails or takes longer, as without a network or while anonymous users are not enabled at the provider, the app starts with a SignedOutSession. In debug mode it prints the error of a sign-in that failed:

The anonymous sign-in failed, so the app has no user: AuthFailure: notConfigured (...)

The app tries again each time the user comes back to it. With firebase_auth, enable Anonymous in the Firebase project: run dart tool/enable_firebase_sign_in.dart again once authMode is anonymous; see Firebase.

Every screen is open although the mode is required​

The mode keeps nobody from a screen on its own. A guard of the routes that reads appSession.allowsApp does, and an app without such a guard shows every screen in every mode. The feature sign_in declares that guard. An app with firebase_auth and without sign_in has none; see an app without the screens.

smf create warns that a route is for users with an account​

A module of the app asks for an account on a route, and no module of the app has a guard that stands for that condition, so every user gets to the screen. The app is generated all the same. Add sign_in, whose guard stands for the condition, or keep the other users away with a guard of your own that reads appSession.hasAccount; see an app without the screens.

In an app without tabs, nothing leads to the account​

The entry of the account is on the settings screen, which a main navigation shows, such as the tabs of bottom_tabs. In an app without a main navigation, no screen leads to the settings screen. Open it from a screen of yours with context.nav.settings.settings().push<void>(), or open the account directly with context.nav.signIn.account().push<void>().

The script says that it cannot tell the sign-in mode of the app​

tool/enable_firebase_sign_in.dart reads the mode from the declaration of authMode in lib/core/auth/app_session.dart. Keep that declaration in the form in which it was generated, on a line that it starts and with a mode as its value:

lib/core/auth/app_session.dart
const AuthMode authMode = AuthMode.required;

A computed value, an indented declaration or a second declaration stops the script, which does not guess.

The script says that firebase.json is missing or has no project​

flutterfire configure writes the Firebase project of the app into firebase.json, and the script reads it from there. Configure the app first, with the command of the section "Firebase" of its README, or name the project:

dart tool/enable_firebase_sign_in.dart --project <id>

When firebase.json has several projects, the script stops and asks you to name one the same way.

The Firebase CLI did not enable the sign-in methods​

The script prints what to try after the Firebase CLI failed:

  • It runs the Firebase CLI in a temporary directory, where an account that firebase login:use chose for the directory of the app does not apply. If the Firebase CLI ran as the wrong account, name the account: dart tool/enable_firebase_sign_in.dart --account <email>.
  • The log of the Firebase CLI, firebase-debug.log, was in that directory, which the script removes. To see what the Firebase CLI did, run the script with --debug.
  • The Firebase console enables the methods too, under Authentication > Sign-in method.

With a Firebase CLI older than 15.6.0, the script stops before that and tells how to update it.

Firebase​

The app stops at start-up with an UnsupportedError​

Firebase is not configured yet, and lib/firebase_options.dart is still the placeholder. Run flutterfire configure in the app, with the command from its README. See Firebase.

flutter run or flutter build ios fails in the phase flutterfire upload-crashlytics-symbols​

The app was configured with flutterfire_cli 1.4.0, whose phase for Crashlytics does not find the upload script where Flutter puts the Swift packages. Activate 1.4.1 and configure the app again on a Mac. See Firebase.

flutter build ipa fails in the phase for Crashlytics​

The phase of flutterfire_cli 1.4.1 does not find the upload script when Flutter archives the app. SMF fixes the phase right after it configures the app, but flutterfire configure writes the phase again each time it runs. After configuring the app yourself on macOS, run the command in the Crashlytics section of the README of the app, which fixes the phase. See Crashlytics and flutter build ipa.

firebase login does not finish on a remote machine​

firebase login waits for the browser to come back to a server on the machine where it runs, which a browser on another machine cannot reach. SMF runs firebase login --no-localhost instead when SSH_CONNECTION, SSH_CLIENT or SSH_TTY has a value, as in a session over SSH. If none of them has one, press Ctrl-C to stop the login, and log in yourself with firebase login --no-localhost. The run goes on without the login and prints the command to configure Firebase later.

SMF says that the Firebase login has expired or is no longer valid​

firebase login:list still lists your account, but Google rejected the login when SMF listed your Firebase projects with firebase projects:list --debug. A login can expire or be revoked, for example when you remove the Firebase CLI's access in your Google account or when your organization asks you to sign in again. Log in again with firebase login --reauth, or over SSH with firebase login --reauth --no-localhost. In a terminal, SMF offers to do this for you. Plain firebase login only says that you are logged in already. Until the login works, flutterfire configure finds no Firebase project and offers to create one.

SMF says that the Firebase login could not be checked​

SMF could not finish listing your Firebase projects with firebase projects:list --debug, so it does not know whether the login works, and it leaves flutterfire configure for later. The warning gives the reason.

A line such as request to … failed, reason: getaddrinfo ENOTFOUND …, or one with ECONNREFUSED, ETIMEDOUT or a certificate error, means that the Firebase CLI could not reach Google. Check your internet connection. Behind a proxy, set HTTPS_PROXY in the terminal that runs smf; the Firebase CLI reads it.

did not finish in 40 s means that no answer came, as happens on a network that drops requests. SMF stops the command after 40 seconds and shows the progress "Checking the machine" while it waits.

Once the network works, run smf create --explain to see the state of every check, then configure Firebase in the app with the command from its README.

The Firebase CLI is installed, but SMF does not find it​

SMF looks for firebase on the PATH of the terminal that runs smf. After installing it yourself, open a new terminal, or add its directory to the PATH, and run smf create --explain to see the state of every check.

SMF says that the Firebase CLI does not run​

SMF runs firebase --version to check the Firebase CLI. A firebase command can be on the PATH and still fail, such as one that runs the Firebase CLI of another Node.js, or a Firebase CLI on a Node.js that is too old for it. The warning says how the command ended. In a terminal, SMF offers to install the Firebase CLI again; see Firebase.

If the old command still does not run after that installation, SMF says so. A new terminal may find it before the new Firebase CLI, as with a Firebase CLI of an older default version of nvm, so remove it.