The Zeroic Journal

Supabase CLI v3: what breaks in your deploys and how to fix it

The new CLI shipped on November 2 and changes what a bare db push does. Here is how to tell whether your deploys are affected, and what to change first.

On this page 7 sections
  1. Who the Supabase CLI v3 change hits
  2. The three failures you will see first
  3. Two changes that alter production without an error
  4. Pin v2 now, then upgrade on purpose
  5. The v3 command map for CI
  6. How to decide what to do this week
  7. WordUp Tutoring: from one build to retainer

Supabase released CLI v3.0.0 on November 2, 2026, and it changes what your deploy scripts do. Database commands now target the local stack unless you pass --remote, and every change to a hosted project needs --yes in CI. A Supabase CLI v3 upgrade breaks unattended deploys in at least three ways, and one of them fails silently.

Supabase’s changelog entry for CLI v3 says npm, Scoop, Linux packages and the supabase/setup-cli GitHub Action install v3 by default, with Homebrew following on November 3. If your CI installs “latest”, your next deploy runs v3 whether you planned the upgrade or not. Supabase also says hosted projects, their data and self-hosted Supabase are not affected: the change is in what the CLI does when it runs, not in your database.

Who the Supabase CLI v3 change hits

You are affected if any of these run Supabase CLI commands without a person at the keyboard:

  • A GitHub Actions or other CI job that runs db push, functions deploy, secrets set or config push.
  • A deploy script on a server or a developer laptop that pipes y into a command or calls supabase-go directly.
  • An AI coding agent such as Claude Code or Cursor running the CLI for you. The v3 migration guide says agents never get a confirmation prompt, even in a terminal, and that the error tells the agent to ask you before it adds --yes.

You are also affected by config changes if your project was created before CLI v2.108.0 and still has an [inbucket] section in supabase/config.toml, or if you use [remotes.<name>] blocks alongside SUPABASE_* environment variables.

You are not affected if your database changes ship only through the Supabase dashboard, or through Supabase’s GitHub integration with no CLI step of your own. The branching GitHub integration docs say you don’t need a GitHub Action to deploy migrations, and its “Deploy to production” option applies new migrations when you merge to the production branch.

This often applies to apps that started on Lovable or Bolt and later moved to their own Supabase project with a hand-written deploy workflow, as in our Lovable Cloud to Supabase checklist. The workflow was set up once, works, and nobody has looked at it since.

The three failures you will see first

1. Deploys fail with HostedMutationConsentRequiredError. Every command that changes a hosted project now asks first, and the default answer is No. Without a terminal, the command fails and changes nothing. The list is long: db push, functions deploy, secrets set, secrets unset, config push, migration repair, db reset and more. echo y | supabase db push no longer confirms anything, and SUPABASE_YES set in supabase/.env or any project env file doesn’t count. Pass --yes on the command, or export SUPABASE_YES=1 in the shell.

2. db push reports success and never reaches production. This is the one to worry about. db push, db pull, db dump, migration list, gen types and the storage commands now target the local stack unless you pass --remote. The migration guide warns that a bare supabase db push in a job that starts a local stack succeeds against that stack and never reaches the hosted project. If your CI starts a local stack to run tests and then pushes, the job goes green and production keeps the old schema. App code that expects the new columns can then break your live app on its next deploy.

3. supabase start stops working. v3 can’t load a config with an [inbucket] section. start, stop, status and the db commands fail with “[inbucket] in supabase/config.toml is no longer supported. Use [local_smtp] instead.” The keys inside the section are unchanged, so the fix is a rename.

Two changes that alter production without an error

These don’t fail loudly, which makes them worse than the three above.

Environment variables now beat config.toml. In v2, a matching [remotes.<name>] block won over SUPABASE_* variables. In v3 the variable wins, and config push sends it. The migration guide’s example: a SUPABASE_AUTH_SITE_URL in .env.local replaces the site_url from [remotes.production]. A developer’s local value can end up as your production auth redirect. Run supabase config diff before your first config push on v3, and set SUPABASE_ENV in CI so .env.development doesn’t apply.

SMS confirmation can flip. The migration guide says v2 applied [auth.sms] enable_confirmations inverted, and v3 applies it as written. The v3.0.0 release notes add that enable_confirmations = false, the value supabase init writes, turns phone confirmation off on config push. If you use phone sign-in, check that setting before your first config push, or phone confirmation can switch on or off in production.

A smaller one: db diff and db pull now use the pg-delta diff engine by default, so the SQL they generate may differ from what you’re used to. If you edit files in supabase/schemas and run db diff, those edits are no longer picked up; use supabase db schema declarative sync instead.

Pin v2 now, then upgrade on purpose

Supabase keeps v2 alive with security and broken-behavior fixes, but no new features. That gives you a safe order of work:

  1. Pin v2 today if CI installs latest. In GitHub Actions, set version: v2.stable on supabase/setup-cli@v3. The setup-cli README says the action needs Node.js 20+ and that moving the action to @v3 alone doesn’t upgrade the CLI. Without a version, the action uses the supabase version pinned in your root lockfile, or latest if there is none.
  2. Run the latest v2 (v2.122.0 or later) and fix its warnings. It warns about removed items and changed defaults. It does not warn about confirmation, precedence, the diff engine or SMS, so check those by hand.
  3. Rename [inbucket] to [local_smtp]. v2.108.0 and later already read the new name, so this is safe before the upgrade.
  4. Rewrite hosted commands. Add --remote at the end of every command meant for production and --yes to unattended changes. --linked, --project-ref and --db-url still work in v3 with a warning, and are removed in v4.
  5. Run supabase stop before upgrading if config.toml has no project_id. Local container and volume names can change, and v3 can start an empty local database.
  6. Install v3, deploy to staging first, and confirm the schema changed there.

Supabase’s own CI/CD workflow guide already shows the v3 form: supabase db push --yes --remote after supabase link.

The v3 command map for CI

v2 command in your workflowv3 equivalent
supabase db pushsupabase db push --yes --remote
supabase db push --db-url "$DB_URL"supabase db push --yes --remote="$DB_URL"
supabase migration list --linkedsupabase migration list --remote
supabase gen types typescript --project-id "$REF"supabase gen types typescript --remote="$REF"
supabase functions deploysupabase functions deploy --yes
supabase secrets set --env-file .env.productionsupabase secrets set --env-file .env.production --yes
supabase config pushsupabase config push --yes
echo y | supabase <command>supabase <command> --yes

Two details from the migration guide trip people up. Attach values with =, as in --remote=<branch>. And move --remote to the end instead of swapping it in where --linked was: migration repair --linked 20240101000000 --status reverted becomes migration repair 20240101000000 --status reverted --remote.

How to decide what to do this week

  • CI installs latest and you deploy this week: pin v2.stable today, then plan the upgrade.
  • CI starts a local stack and then runs db push: add --remote before anything else. This is the silent failure.
  • An AI agent runs your Supabase commands: keep --yes out of its instructions for production. Let it stop and ask, which is what v3 now makes it do.
  • You use [remotes.<name>] blocks: run env | grep ^SUPABASE_ in CI and supabase config diff before the first v3 config push.
  • You only deploy through the dashboard or the GitHub integration: nothing to change in production. Upgrade your local CLI when convenient and rename [inbucket].
  • You don’t know which of these applies: open your deploy workflow file and search for supabase. Every line it finds is on the list above.

WordUp Tutoring: from one build to retainer

We built WordUp Tutoring’s learning app for K-8 students on Next.js and Supabase as one fixed-scope build, and WordUp then moved to a retainer, with our engineer building the AI into the product. You can read the WordUp Tutoring case study for what that covered.

A retainer is where a change like CLI v3 belongs. A major version of a tool in your deploy path is easy to miss when nobody owns the pipeline, and cheap to handle when the engineer who wrote the workflow is still on the team. If your Supabase app was built by a contractor who has moved on, our senior developer retainers put that ownership back, and our Supabase and Next.js developers page covers the stacks we work in. If the app came out of a vibe-coding tool, our notes on taking a vibe-coded MVP to production cover the rest of what to check.

Frequently asked questions

Do I have to upgrade to Supabase CLI v3 right away?
No. Supabase keeps v2 alive with security and broken-behavior fixes, though no new features. You can pin v2.stable in npm, Homebrew, Scoop or the setup-cli GitHub Action and upgrade on your own schedule. Pin first if your CI installs the latest CLI, because every install channel now gives you v3 by default.
Why does supabase db push fail in GitHub Actions after the upgrade?
Because v3 asks for confirmation before any change to a hosted project, and CI has no terminal to answer it. The command fails with HostedMutationConsentRequiredError and changes nothing. Add --yes to the command and --remote so it targets the hosted project. Piping y into the command no longer works, and SUPABASE_YES in a .env file does not count.
Does Supabase CLI v3 change my hosted database or my live app?
No. Supabase says hosted projects, their data and self-hosted Supabase are not affected by the release. The CLI changes how commands behave on the machine that runs them: which database they target, when they ask for confirmation and which config values win. Your live app only changes when one of those commands runs against it.
What is the fastest way to find what v3 will break in my project?
Update to the latest v2 release, v2.122.0 or later, and run your normal workflows, including CI. That release prints warnings for removed items and for commands whose default target changes. It does not warn about confirmation, config precedence, the new diff engine or the SMS setting, so check those four by hand before you install v3.

References

  1. Supabase changelog - Supabase CLI v3 breaking change
  2. Supabase docs - Migrating to Supabase CLI v3
  3. Supabase CLI v3.0.0 release notes on GitHub
  4. supabase/setup-cli GitHub Action README
  5. Supabase docs - Branching GitHub integration
  6. Supabase docs - Managing environments with CI/CD

More from the journal

Hear from Prashant within 24 hours.

Prashant Abbi Partner @ Zeroic

Not sure what your Supabase deploys will do on v3? Send us your deploy workflow. A senior engineer will tell you which commands change behavior on v3 and what to pin or rewrite before your next release.

See senior developer retainers, or book a 30-minute call