Missing required field in config: db.port

[willmaclean]

Describe the bug Hey! relatively new supabase user, been bashing my head on this. Super stumped...

Supabase CLI v2.47.2 fails to recognize the db.port field in config.toml, despite the field being present and properly formatted according to TOML standards. This prevents all CLI commands from running, including supabase link, supabase status, and supabase start. The error "Missing required field in config: db.port" occurs even though the field exists and can be successfully parsed by standard TOML libraries.

To Reproduce Steps to reproduce the behavior:

1. Create or use an existing Supabase project with supabase/config.toml file
2. Ensure the [db] section contains port = 54322 (or any valid port number)
3. Run supabase link --project-ref <project-ref> --password <db-password>
4. See error: "Missing required field in config: db.port"
5. Verify the config is valid: python3 -c "import tomllib; f=open('supabase/config.toml','rb'); data=tomllib.load(f); print('db.port:', data.get('db',{}).get('port'))"
6. Observe that Python successfully reads db.port: 54322, confirming the TOML is valid

Expected behavior The CLI should successfully parse the db.port field from config.toml and proceed with the link command (or any other CLI command).

Screenshots

$ supabase link --project-ref grosxzvvmhakkxybeuwu --password "$SUPABASE_PASSWORD" --debug
Using project host: supabase.co
Supabase CLI 2.47.2
Loading project ref from flag: grosxzvvmhakkxybeuwu
Missing required field in config: db.port

Config file content:

[db]
# Port to use for the local database URL.
port = 54322
# Port used by db diff command to initialize the shadow database.
shadow_port = 54320
# The database major version to use. This has to be the same as your remote database's. Run `SHOW
# server_version;` on the remote database to check.
major_version = 17

System information

• Ticket ID: c0f9719b26c643e2acfe7e4575b0dcc9
• Version of OS: macOS Sequoia (Darwin 24.4.0)
• Version of CLI: v2.47.2
• Version of Docker: v28.0.4
• Versions of services: Unable to run supabase services due to this bug blocking all CLI commands

Additional context

Troubleshooting attempts (all failed):

1. Used --workdir flag:

   $ supabase link --workdir ./supabase --project-ref <ref> --password <pwd>
   Using workdir ./supabase
   Missing required field in config: db.port
   

2. Ran from supabase directory:

   $ cd supabase && supabase link --project-ref <ref> --password <pwd>
   Using workdir /Users/will/code/service
   Missing required field in config: db.port
   

3. Regenerated config with supabase init --force: Fresh config generated, same error persists

4. Completely removed and recreated supabase directory:

   $ rm -rf supabase && supabase init
   $ supabase link --project-ref <ref> --password <pwd>
   Missing required field in config: db.port
   

5. Tried older CLI version (v1.200.3): Downloaded from GitHub releases, but it doesn't support Postgres 17 or newer config format:

   Unknown config fields: [db.migrations db.migrations.enabled ...]
   Failed reading config: Invalid db.major_version: 17.
   

6. Verified no hidden characters or encoding issues:

   • File encoding: UTF-8 text ✓
   • No unusual whitespace or hidden characters detected via od -c ✓
   • TOML parses successfully with Python's tomllib ✓

Impact: This bug completely blocks all Supabase CLI functionality. Cannot link projects, check status, start local development, or run any CLI commands.

Environment details:

• Platform: darwin arm64
• Installation Method: Homebrew (brew install supabase/tap/supabase)
• Version of Node.js: v22.18.0
• Repository has existing migrations in supabase/migrations/

[htxryan]

Was hitting the same issue, but I found this which seems to work for me as a workaround for now. I know you noted this doesn't work for you, but for me it does (perhaps because I don't need the project ref). Just dropping this here in case anyone else comes across this.

https://www.answeroverflow.com/m/1395976057105940611

supabase start --workdir ./supabase

[willmaclean]

Thanks for the comment! Sadly, I did see that thread and running like that still doesn't work for me.

[rtman]

that was me in that thread, I'm circling back to this as I seem to have to upgrade now. But I'm now getting the issue again. Is there any update on this from the supabase team?

[rtman]

The workdir approach in the other thread does seem to work, but it creates a new supabase dir within the existing one. Not sure why that works but it does. Maybe its a monorepo issue?

[rtman]

FYI I fixed this by moving my supabase directory out of one of my monorepo packages to its own package. For whatever reason, it did not like being inside a package, but is fine being its own package. Something changed in v2, as this worked in v1 fine.

before:

monorepo -packages --server ---supabase

after:

monorepo -packages --server --supabase

[mlanza]

I second this issue and already spent a few hours on it. I was deploying from the CLI earlier today. I don't know what I did to cause things to break, but they did. And I can't get past it.

[mlanza]

Solved. I had been fooling with my .zshenv file and I added an env var which apparently clobbered something the CLI relied on. I dropped the new env var and problem vanished!

[manolopanama]

I have the same issue =/

[manolopanama]

The problem was indeed an environmental variable. SUPABASE_DB is causing issues. I introduced this variable in my application. I renamed from SUPABASE_DB to SUPABASE_DATABASE both in my application and in .env file and it fixed the issue!