Blank page after deploy, and the console says "supabaseUrl is required."

Your Vite + Supabase app works on your machine. You deploy it, and the live site is a blank white page. The build log was green. Open the browser's developer console and you see:

Uncaught Error: supabaseUrl is required.

That's the error supabase-js throws when createClient gets an empty URL. Its URL check trims the value and, if nothing is left, runs throw new Error('supabaseUrl is required.') (supabase-js source: helpers.ts). In a Vite app, it almost always means VITE_SUPABASE_URL wasn't set when the deployed build ran. Your client file creates the client as soon as the app loads, so the error stops the app before anything renders.

The fix

1. Confirm it's this error (Verified). Open the live site, open developer tools, and look at the Console. These are the supabase-js messages and what they mean:

• supabaseUrl is required. means the URL was empty when the build ran.
• supabaseKey is required. means the URL was there but the key was empty (supabase-js source: SupabaseClient.ts).
• Invalid supabaseUrl: Must be a valid HTTP or HTTPS URL. means a value was set but isn't a full URL, for example the project host without https:// (supabase-js source: helpers.ts).

We got each of these in our test build, each with an empty <div id="root"> and a blank page (Verified).

2. Check the variable names in your client code (Verified). Supabase's React quickstart reads exactly these two names:

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY

(Supabase: Use Supabase with React). If your code reads an anon-key name such as VITE_SUPABASE_ANON_KEY, that's fine too: Supabase calls anon the "Legacy version of publishable keys" (Supabase: API keys). Whatever names your code reads, those are the names your host needs, character for character, including the VITE_ prefix. Vite only exposes prefixed variables to the browser: "Variables prefixed with VITE_ will be exposed in client-side source code after Vite bundling", and its example shows an unprefixed DB_PASSWORD reading as undefined (Vite: Env Variables and Modes). In our test, a build with SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY set (no prefix) still crashed with supabaseUrl is required. (Verified).

3. Set them in your host's build environment (Verified locally; your host's settings screen is Docs-only). Add VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY (or your anon-key name) in your host's environment variables for the build, for the environment you deploy (production, preview, or both). The values are the Project URL and publishable key from your project's Connect dialog (Supabase: API keys). Vite reads variables that already exist in the environment first: they "have the highest priority and will not be overwritten by .env files" (Vite: Env Variables and Modes). In our test, a build with no .env file and the two variables set in the environment loaded normally (Verified).

4. Rebuild and redeploy (Verified). Saving a variable doesn't change the site you already deployed. Vite's env values are "statically replaced at build time" (Vite: Env Variables and Modes), so the broken build has the empty value baked in. In our test, the already-built files were byte-for-byte unchanged after we set the variables, still crashed, and loaded once we rebuilt (Verified). Start a fresh build after you change a variable.

5. Check the rebuilt site (Verified). Reload the live site with the console open: the error should be gone. To check the bundle itself, open the main JavaScript file under /assets/ (it's in the page source or the Network tab) and search for your project URL. In a working build, the URL and publishable key appear as plain text. In the broken build, the URL never appears, and the client is created with void 0 (undefined) in place of both values (Verified).

Optional: fail with a clearer message (Verified). A check before createClient names the variable and the fix, so the next person sees more than a blank page and a library error:

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY

if (!supabaseUrl || !supabasePublishableKey) {
  throw new Error(
    'VITE_SUPABASE_URL or VITE_SUPABASE_PUBLISHABLE_KEY was not set when this build ran. ' +
    "Add it to your host's build environment variables, then rebuild and redeploy."
  )
}

export const supabase = createClient(supabaseUrl, supabasePublishableKey)

The page is still blank without the variables, but the console now says which ones are missing (Verified). It doesn't replace step 3.

Tested October 26, 2026 with Vite 8.3.5, @vitejs/plugin-react 6.1.2, React 19.3.1 and @supabase/supabase-js 2.118.0 on Node 20, using the client file from Supabase's React quickstart. We served each build locally and loaded it in headless Chrome. The URL was a local placeholder and the key a made-up sb_publishable_ value, and no requests left the machine. With no variables, the build succeeded, #root stayed empty, and Chrome logged "Uncaught Error: supabaseUrl is required." With the variables in .env or in the build environment, the app rendered. Unprefixed names, a missing key, a URL without https://, and setting variables without rebuilding each kept the page blank, with the errors listed above.

Why it happens

• Your .env file usually isn't part of the deploy. Supabase's React quickstart puts the URL and key in .env.local (Supabase: Use Supabase with React), and Vite's docs label .env.local "ignored by git" (Vite: Env Variables and Modes). If your host builds from your repo, that file never gets there, so the build runs without the values.
• Vite bakes the values in at build time. Missing at build time means missing in the deployed JavaScript, even if you add them later. The build doesn't fail, because Vite replaces an unset variable with undefined (Vite: Env Variables and Modes).
• The Supabase client is created when the app loads. The usual setup calls createClient at the top level of a shared file, which every page imports. When that throws, the app's code stops before React (or any framework) renders, so the page stays blank.
• Local dev hides it. Locally, Vite loads your .env files at startup (".env files are loaded at the start of Vite. Restart the server after making changes", Vite: Env Variables and Modes), so the app works on your machine.

For the other ways a Vite variable ends up undefined (like process.env instead of import.meta.env), see Why is my env var undefined in the deployed Vite app?

What not to do

• Don't put a secret key in a VITE_ variable to get past the error. Every VITE_ value ships to every visitor. Vite: "VITE_* variables should not contain sensitive information such as API keys" (Vite: Env Variables and Modes). Use the publishable key (sb_publishable_...) or the legacy anon key. Supabase: "A secret key bypasses every Row Level Security policy you have. Never put one in a browser, a shipped application, or source control." That covers sb_secret_... and the legacy service_role key (Supabase: API keys). More: Is the publishable key safe? and Check what your build ships.
• Don't commit your .env file to make the deploy work. Set the values in the host's build environment instead. Vite says to add *.local to .gitignore (Vite: Env Variables and Modes).
• Don't hard-code a fallback secret in the client file. A publishable URL and key in code are public anyway. Anything else stays out of frontend code.
• Don't keep redeploying the same build. Changed variables need a fresh build.

AI prompt

My Vite + Supabase app is a blank page after deploy, and the console says
"Uncaught Error: supabaseUrl is required."
1. Find where createClient is called and list the exact import.meta.env names it reads.
2. Tell me which variable names and values I need to add to my host's BUILD environment
   variables, and remind me to rebuild and redeploy after adding them.
3. Make sure only the Project URL and the publishable (or anon) key are in VITE_ variables.
   If any VITE_ variable holds a secret, sb_secret_ or service_role key, flag it and
   move that code to a server or Edge Function instead.
4. Add a check before createClient that throws a clear error naming the missing variable.
5. Don't commit .env files. Show me the diff first and wait for my OK.

How to verify (two accounts)

Once the page loads, check that the client is only as powerful as the publishable key should be:

1. Signed out: open the live site in a private window. It should load with no console errors, and show only what you meant to be public.
2. Two accounts: sign in as user A and create something private. Sign in as user B in another browser. B shouldn't see A's data. If B can, the problem is your Row Level Security policies, not your env vars. Start with our Supabase RLS guide.
3. If the page loads but data calls fail with 42501 permission denied or return an empty array, the client is working and you're at the grants-and-policies step. Supabase: "A missing grant returns a permission error… whereas a policy that matches no rows returns an empty result" (Supabase: API keys).

Related

Check what your build ships: secret keys in frontend env vars · Is the publishable key safe? · Invalid API key (Supabase) · Rotating secrets after a host exposure · 42501 permission denied for table · Our Supabase RLS guide

Your turn

Was it the missing variable, a missing prefix, or a build that didn't rerun? Tell us which, and we'll keep this list in order of what people actually hit.