cannot+find+project+ref+have+you+run+supabase+link

Not specified by the original author.

Supabase CLI: Cannot find project ref. Have you run supabase link?

TL;DR: the CLI does not know which remote project you mean. Link it once with supabase link --project-ref [ref] (find the ref in the dashboard URL), entering the database password when prompted. If it used to work, the link config was deleted or you are in a different directory: re-link. Unlink and re-link if the stored ref points at the wrong project.

Cannot find project ref. Have you run supabase link?

Steps

1. Run supabase link --project-ref [ref] using the ref from the project's dashboard URL. Enter the database password when prompted.
2. Confirm the link: check that the project config now records the ref, then rerun the failing command. Expected: it targets the linked project instead of erroring.
3. If it worked before, check you are in the same project directory — the link is per-directory. Re-link in the right directory if needed.
4. Wrong project linked: run supabase unlink, then link again with the correct ref.

When this applies

• the exact Cannot find project ref. Have you run supabase link? message
• a fresh clone where nobody ran supabase link yet
• commands run from a different directory than the linked one

When it doesn't

• Authorization failed for the access token and project ref pair — linking itself is failing, fix that
• database password rejections after a successful link
• dashboard-side project deletion (linking to a deleted ref fails differently)

Compatibility

Supabase CLI supabase link/unlink; per-directory link config. Verified against the themehackers CLI unlink side-effects notes.

Variant phrasings

• supabase cannot find project ref have you run supabase link
• supabase link project ref fix
• supabase cli not linked error

Root cause

Most supabase commands resolve the remote project from local link state, not from arguments. With no link state there is no project ref to send, so the CLI aborts before doing anything.

Edge cases

• the link is per working directory; monorepos need a link in each package that calls the CLI
• unlinking does not delete remote resources, it only clears local state
• CI should link once during setup, not on every command

Supabase CLI commands that target a remote project fail with Cannot find project ref. Have you run supabase link? when the local project was never linked or the link state was lost (wrong directory, deleted config). The verified fix: run supabase link with the correct project ref, re-link in the right directory, or unlink and re-link if the stored ref is wrong. Source: https://github.com/themehackers/cli/blob/HEAD/apps/cli/src/commands/unlink/SIDE_EFFECTS.md

Not specified by the original author.

supabase link: Authorization failed for the access token and project ref pair

TL;DR: your CLI access token and the project ref you passed do not belong together — the token is stale/revoked, or the ref is for a different project or org than the token can see. Run supabase login again to mint a fresh token, copy the project ref from the dashboard URL of the project you actually want, and re-run supabase link --project-ref [ref].

LegacyLinkAuthTokenError: Authorization failed for the access token and project ref pair

Steps

1. Run supabase login and complete the browser flow. Expected: login succeeds and a fresh access token is stored.
2. Open the project in the dashboard and copy the project ref from the URL — do not guess it from the project name.
3. Run supabase link --project-ref [ref] with that exact ref. Expected: linking succeeds and config.toml records the project.
4. Still failing: check that the logged-in account actually has access to the project (right org, not removed). Tokens cannot see projects they were never granted.

When this applies

• the exact Authorization failed for the access token and project ref pair error on supabase link
• linking after the access token was revoked or the account changed teams
• a ref copied from a different project's dashboard URL

When it doesn't

• database password failures — those happen after linking succeeds
• Cannot find project ref on other commands — the link never completed, fix that
• dashboard access issues in the browser itself

Compatibility

Supabase CLI supabase login / supabase link; access tokens (sb_token) and project refs. Verified against the kw-login-supabase-cli community skill.

Variant phrasings

• supabase link authorization failed access token project ref
• supabase LegacyLinkAuthTokenError fix
• supabase link invalid project ref

Root cause

The CLI validates the token/project-ref pair against the Supabase API at link time. A token minted for account A, or a ref belonging to a project the token cannot access, fails the pair check even though each value looks fine on its own.

Edge cases

• project refs are not secret but tokens are; never paste the token into the link command output you share
• switching between personal and org accounts needs a fresh supabase login each time
• old CLI versions produce less clear variants of this error; upgrade if the message differs

supabase link validates the CLI access token together with the project ref; when they do not belong to the same accessible project the CLI fails with LegacyLinkAuthTokenError: Authorization failed for the access token and project ref pair. The verified fix from the community skill: re-run supabase login for a fresh token, copy the exact project ref from the dashboard URL, and link again. Source: https://github.com/kwazema/claude-skills/blob/HEAD/skills/kw-login-supabase-cli/SKILL.md

Not specified by the original author.

TL;DR

Run your app and tests against local. Run the app against the branch with production-like data volume.

Steps

1. supabase init once, supabase start to boot the local stack. Develop against local: same Postgres, same Auth, same Storage, none of it shared.
2. Every schema change is a migration file (supabase db diff to capture, or hand-written). No hand edits to the local database that are not captured in a migration.
3. Run your app and tests against local. Auth flows, RLS policies, and edge functions all run locally; verify the full critical path before pushing anything.
4. Link the project (supabase link) and push migrations to a preview branch first. Run the app against the branch with production-like data volume.
5. Push to production only from the branch-verified migration set. After pushing, supabase db diff against production must be empty.
6. Migration files are the unit of promotion. Code that depends on a schema change ships with or after the migration, never before. Seed data for local dev lives in seed files, not in migrations.

When to use

You are seeing this: The Supabase CLI gives you the whole stack locally. Use this skill when you run into "Supabase local dev to production: CLI workflow that keeps environments converged".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/local-development/cli/getting-started