Troubleshooting

Start here

Most "this used to work" problems are a missing tool or one that is too old, so before you read any further, ask the CLI:

floot requirements check

It probes Git, the Dart SDK, FVM, Flutter, Docker, the Supabase CLI, Deno, jq, OpenSSL, the Stripe CLI and your platform toolchains, and reports which of them are absent or below the version this project needs. It exits non-zero when anything is wrong, which makes the repair a one-liner:

floot requirements check || floot requirements install

floot requirements install installs the missing ones through your host's package manager, asking before it touches anything. See the CLI reference for the full flag list.

Environment

Every Edge Function fails to boot

ENV VALIDATION FAILED: {
  formErrors: [],
  fieldErrors: {
    SB_SECRET_KEY: [ "Invalid input: expected string, received undefined" ]
  }
}

The whole environment is validated the moment any Edge Function starts, and throws if the shape is wrong. Because every function shares that validation, one missing variable takes them all down at once, which is the point: a half-configured backend should fail at functions serve rather than at the first request that needed the variable.

Read the fieldErrors keys: each one names a variable in supabase/.env.local. If they name every required key below at once, no variable is wrong: the file was not loaded at all. See Every auth email fails to send.

These are required in every project, whatever it was generated with:

DATABASE_WEBHOOK_SECRET, DENO_ENV, ENABLE_MULTI_TENANCY, SMTP_FROM, SMTP_HOST, SMTP_PASSWORD, SMTP_PORT, SMTP_USER, SB_URL, SB_PUBLISHABLE_KEY, SB_SECRET_KEY, SB_AUTH_EXTERNAL_REDIRECT_URI, SB_SEND_EMAIL_HOOK_SECRET, SB_STORAGE_URL, WEBSITE_URL.

The rest are optional until a feature flag turns them mandatory. The message says so in as many words: STRIPE_SECRET_KEY is required when ENABLE_STRIPE is "true".

Every auth email fails to send

Unexpected status code returned from hook: 500

Auth sends every email (sign-up confirmation, sign-in link, password reset, email change) through the send-email Edge Function, and answers this when the function fails. In the app, the login page's passwordless button shows "Sorry an unexpected error occurred. Please try again."

On a local stack, the usual cause is that supabase functions serve is not running. supabase start runs an edge runtime too, but it does not load supabase/.env.local, so every function fails validation with every required key missing (Every Edge Function fails to boot). Serve the functions from supabase/ and leave the command running:

supabase functions serve --env-file .env.local --import-map ./functions/deno.json --no-verify-jwt

A release build throws on startup

Exception: Error loading .env: <the underlying failure>
Release builds read `.env`, which is git-ignored and is not created by
`floot create`. Copy `.env.local` to `.env`, replace the local values with your
production ones, then add `- .env` under `flutter: assets:` in pubspec.yaml:
an asset that is not listed there is not bundled.

The message names the remedy, but here is the reasoning behind it.

Debug and profile builds load .env.local; release builds load .env. Every .env* file is git-ignored, and floot create writes only .env.local, so until you create .env yourself, the first release build you run throws here, before a single frame is drawn.

There is a second way to hit this with the file sitting right there on disk: Flutter reads it as a bundled asset, so .env must also be listed under flutter: assets: in pubspec.yaml. floot create lists .env.local and not .env, for the same reason it writes one and not the other.

Database webhooks fail after you change a secret

401 INVALID_SIGNATURE. Failed to verify the request.

Five values in supabase/.env.local are also read from the Supabase Vault by SQL, under lowercase names, because Postgres cannot see your environment file:

The [db.vault] block in supabase/config.toml seeds them locally, but only when the database volume is created. A plain supabase stop && supabase start restores the saved volume and skips seeding entirely, so the Vault keeps whatever it was seeded with the first time.

That is what the 401 above is: the database signs the webhook with the stale database_webhook_secret while the Edge Function verifies it against the fresh DATABASE_WEBHOOK_SECRET from supabase/.env.local. Every database-driven function is affected at once.

supabase stop --no-backup && supabase start

Supabase

The initial migration refuses to run

ERROR: realtime.messages does not have RLS pre-enabled. This project requires the realtime image shipped with Supabase CLI >= 2.116.0 (older images leave RLS disabled, which would expose private broadcast topics). Upgrade the Supabase CLI and rerun.

This is a deliberate guard in supabase/migrations, not a bug. Since 2.116.0 the realtime image owns realtime.messages and ships it with row-level security already enabled; postgres may add policies to it but can no longer ALTER it. On an older image RLS stays off, the subscription-topic policies protect nothing, and any signed-in user can subscribe to any topic, so the migration stops rather than build that.

floot requirements check supabase

supabase stop --no-backup && supabase start

Android

Emulator is not reaching the backend

Connection refused - errno 101

SocketException: Connection failed (OS Error: Network is unreachable, errno = 101)…

Connection refused - errno 111

SocketException: Connection refused (OS Error: Connection refused, errno = 111)…

This occurs because the Android emulator does not recognize localhost as the host machine. Instead, you should use the IP address 10.0.2.2. The port stays 54321, that is the local Supabase API, which is what the app talks to.

SUPABASE_URL=http://10.0.2.2:54321

If you would rather keep 127.0.0.1 and avoid a separate Android-only SUPABASE_URL, forward the port instead; see Useful Commands.

Deep links

The link opens the browser, not the app

A Stripe return or an invitation lands on the web app even though the app is installed. That is the designed fallback, so nothing errors: the platform did not verify your domain for the app, or does not hand links over at all. First rule out the platforms that never open the app from a link: Windows, Linux, a Mac that is not opted in, and any Mac whose default browser is Chrome, Arc or Edge (see When the link misses the app).

Then check the chain in order; each step depends on the one before. The examples use app.myapp.com, the bundle id com.acme.myApp and the package com.acme.my_app.

curl -sI https://app.myapp.com/.well-known/apple-app-site-association
curl -sI https://app.myapp.com/.well-known/assetlinks.json

curl -s https://app-site-association.cdn-apple.com/a/v1/app.myapp.com

keytool -list -v -keystore ~/upload-keystore.jks -alias upload | grep SHA256

adb shell pm get-app-links com.acme.my_app

adb shell pm verify-app-links --re-verify com.acme.my_app

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -u <path to the old .app>

Flutter

Widget Testing

Pending timers

When running widget tests, you might encounter the following error:

The following assertion was thrown running a test: A Timer is still pending even after the widget tree was disposed.

…'!timersPending’

This typically occurs when an animation or asynchronous operation hasn't completed. Below are two approaches to resolve this using tester.runAsync.

await tester.runAsync(() async => tester.pumpAndSettle());

Apple build failures (Swift Package Manager)

Floot builds all iOS/macOS plugins with Swift Package Manager; there is no CocoaPods integration, and your project has no Podfile. If you see an error mentioning pod install or CocoaPods's specs repository, it is coming from a stale build directory rather than from Floot.