Slik fikser du at Supabase API-nøkkel ikke finnes i miljøvariabler
Sist verifisert: 11. september 2026. Du legger til Supabase-URL-en og API-nøkkelen i en .env-fil, starter appen på nytt, og får fortsatt en feil som “Supabase API key not found” eller Supabases egen supabaseKey is required. I de fleste tilfeller finnes nøkkelen et sted, men koden som kaller createClient() mottar undefined eller en tom streng.
Det er også en viktig navneendring fra 2026 bak mange forvirrende opplæringsguider. Supabase faser ut de eldre anon- og service_role-API-nøklene innen utgangen av 2026 og anbefaler nå publishable-nøkler for offentlig/klientkode og secret-nøkler for betrodd serverkode. Eksisterende eldre nøkler kan fortsette å fungere under migrasjonen til du deaktiverer dem, men navnet på miljøvariabelen din og koden din må fortsatt matche nøyaktig.
Ikke sett sb_secret_... i en variabel som er ment å være eksponert for nettleserkode, som en Vite VITE_*-variabel eller en Next.js NEXT_PUBLIC_*-variabel. Supabase sier at hemmelige nøkler omgår Row Level Security og må holdes i utviklerkontrollerte backend-komponenter.
Trinn 1: bekreft at verdien faktisk mangler ved kjøretid
Begynn ikke med å regenerere nøkler eller reinstallere pakker. Bevis først hva applikasjonen din mottar.
Den gjeldende @supabase/supabase-js-klienten sjekker det andre argumentet som sendes til klientkonstruktøren og kaster supabaseKey is required. når verdien er falsk. Du kan se denne oppførselen i den offisielle supabase-js-kilden.
AI-generert illustrasjon av en manglende Supabase API-nøkkel-feil. Det er ikke et skjermbilde fra et ekte prosjekt, og stakksporet er illustrerende.
Ikke skriv ut hele den hemmelige nøkkelen. For feilsøking er en boolean eller forventet prefiks nok. En publiserbar nøkkel er designet for offentlige komponenter, men å logge fullstendige legitimasjoner er fortsatt unødvendig; en hemmelig nøkkel må aldri eksponeres i klientlogger.
Merk også at TypeScript-syntaks som process.env.MY_KEY! eller process.env.MY_KEY as string ikke oppretter en manglende verdi ved kjøretid. Det endrer bare hva TypeScript tror om typen. Hvis miljøvariabelen er fraværende, mottar Supabase fortsatt undefined.
Egenkontroll: hvis booleanen for nøkkelen er false, slutt å feilsøke Supabase-tillatelser, autentisering eller Row Level Security. Applikasjonen har ikke lastet konfigurasjonen ennå.
Trinn 2: bruk gjeldende nøkkeltype – og sørg for at gamle og nye navn er konsistente
Åpne Supabase-prosjektets Connect-dialog, eller gå til Settings → API Keys. Supabases gjeldende dokumentasjon identifiserer eksplisitt Settings → API Keys som stedet for å vise alle prosjektets API-nøkler.
For kode som sendes til en brukers nettleser, mobilapp, skrivebordsapp eller andre offentlige komponenter, bruk en publishable key. Supabase sier at den publiserbare nøkkelen er trygg å eksponere fordi databasetilgang fortsatt styres av grants og Row Level Security. For backend-komponenter som du har full kontroll over, gir en secret key utvidet tilgang og omgår Row Level Security.
Migreringen fra eldre nøkler er en vanlig årsak til en “not found”-feil fordi følgende kombinasjoner ikke er ekvivalente som miljøvariabelnavn:
Koden leser
Miljøet definerer
Resultat
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
Matcher
NEXT_PUBLIC_SUPABASE_ANON_KEY
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
Gammel kode leser undefined
VITE_SUPABASE_PUBLISHABLE_KEY
SUPABASE_PUBLISHABLE_KEY
Vite-klienten eksponerer ikke variabelen uten prefiks som standard
process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
VITE_SUPABASE_PUBLISHABLE_KEY
Feil rammeverk-navngivning/tilgangsmønster
En eldre variabel som NEXT_PUBLIC_SUPABASE_ANON_KEY er ikke automatisk ugyldig. Hvis prosjektet ditt fortsatt har en aktiv eldre anon-nøkkel og koden din leser nøyaktig den variabelen, kan den fortsette å fungere under Supabases migreringsperiode. Problemet er å kopiere en ny publiserbar nøkkel til ett variabelnavn mens koden fortsatt leser et annet.
Egenkontroll: søk i prosjektet ditt etter SUPABASE_. Sammenlign hvert variabelnavn i koden med de nøyaktige navnene i miljøfilene og utplasseringsinnstillingene dine. Ikke stol på hukommelsen.
Trinn 3: plasser .env-filen der rammeverket faktisk laster den
En korrekt nøkkel på feil filplassering er i praksis en manglende nøkkel.
AI-generert prosjektetre-illustrasjon som viser miljøfilen på applikasjonsroten. Det er ikke et skjermbilde av en spesifikk IDE eller rammeverkprosjekt.
Next.js: hold .env-filer i prosjektrøtten
Next.js har innebygd støtte for .env*-filer. Dens gjeldende miljøvariabelguide sier at hvis du bruker en /src-katalog, tilhører miljøfilene fortsatt prosjektrøtten, ikke inne i /src. Se den offisielle Next.js miljøvariabelguiden.
En typisk oppsett er:
my-app/
.env.local
package.json
next.config.js
app/
src/ # if used
For nettlesersidekode eksponerer Next.js bare variabler som bruker NEXT_PUBLIC_-prefikset. Disse verdiene inlines i nettleser-bundlen ved byggetidspunktet.
Vite: bruk VITE_ og import.meta.env
Vite eksponerer klientmiljøvariabler gjennom import.meta.env. Som standard eksponeres bare navn med prefikset VITE_ til klientkode. Den offisielle Vite Env Variables and Modes-guiden dokumenterer dette direkte.
fordi det mangler det standard VITE_-eksponeringsprefikset.
Node/serverkode: ikke kopier nettleserprefikser blindt
Serverkode leser normalt fra process.env. Hvis en nøkkel ikke trenger å være tilgjengelig i nettleseren, ikke legg til et offentlig prefiks bare for å gjøre den synlig. Supabase advarer spesifikt om at hemmelige nøkler er backend-only.
Egenkontroll: verifiser tre ting sammen: env-filen er i applikasjonsroten, variabelnavnet bruker riktig rammeverk-prefiks, og koden bruker rammeverkets korrekte tilgangsmetode – process.env for Next.js/Node eller import.meta.env for Vite-klientkode.
Trinn 4: start utviklingsserveren på nytt etter endring av miljøfiler
Miljøvariabler lastes vanligvis når utviklingsprosessen starter. Vite dokumenterer eksplisitt at .env-filer lastes ved oppstart og at du bør starte serveren på nytt etter endringer.
Stopp den gjeldende prosessen og start den på nytt:
# Next.js
npm run dev
# Vite
npm run dev
AI-generert terminalillustrasjon av å starte en utviklingsserver på nytt og nå en ren oppstart. Det er ikke utdata fra en ekte Supabase-utplassering.
Hvis feilen dukket opp bare etter at du opprettet miljøfilen mens serveren allerede kjørte, kan en omstart være hele fiksen.
Egenkontroll: kjør de midlertidige boolean-sjekkene på nytt. Hvis verdiene nå er lastet, fjern unødvendig feilsøkingsutdata og fortsett til normal Supabase-drift.
Bruk en kjøretidsvakt i stedet for å skjule problemet med TypeScript
Et nyttig produksjonsmønster er å feile med en klar konfigurasjonsmelding før du kaller Supabase:
import { createClient } from '@supabase/supabase-js'
const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
if (!supabaseUrl) {
throw new Error('NEXT_PUBLIC_SUPABASE_URL is missing')
}
if (!supabaseKey) {
throw new Error('NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY is missing')
}
export const supabase = createClient(supabaseUrl, supabaseKey)
AI-generert kodeillustrasjon av å sjekke konfigurasjonen før du kaller createClient(). Det er et konseptuelt eksempel, ikke et skjermbilde fra Supabase SDK-dokumentasjonen.
når du feilsøker, fordi non-null-assertionen kan skjule TypeScript-advarselen uten å endre kjøretidsverdien.
Hvis det fungerer lokalt men feiler etter utplassering
Dette er vanligvis et utplasseringsmiljøproblem, ikke et Supabase-prosjektproblem.
Lokale .env.local-filer committes normalt ikke til Git – og bør ikke behandles som en produksjonsmekanisme for hemmelighetslevering. Konfigurer de samme variabelnavnene i hostingleverandørens prosjektinnstillinger.
For eksempel dokumenterer Vercel separate Production, Preview og Development-miljøer. Det sier også at endringer i miljøvariabler kun gjelder nye utplasseringer, så du må utplassere på nytt etter å ha lagt til eller endret dem. Se Vercels offisielle guide for håndtering av miljøvariabler.
Sjekk:
Er variabelen definert for Production, ikke bare Preview?
Matcher navnet nøyaktig koden?
Oppstod en ny utplassering etter at variabelen ble lagt til?
Var den offentlige variabelen til stede da klientbundlen ble bygget?
Next.js offentlige variabler er byggetidsverdier
Next.js dokumenterer at NEXT_PUBLIC_*-variabler inlines i nettleser-JavaScript ved byggetidspunktet. Etter at appen er bygget, endrer ikke endringer i kjøretidsmiljøet disse verdiene i den eksisterende klientbundlen. Hvis du bygger et Docker-bilde uten NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY og senere injiserer den bare når containeren starter, kan nettleserkoden fortsatt inneholde den manglende byggetidsverdien.
Fiks: oppgi offentlige Supabase-verdier under bygget som produserer klientbundlen, eller redesign applikasjonen til å gi kjøretidskonfigurasjon gjennom en serverkontrollert mekanisme.
Vite erstatter også klientenv-verdier under bygget
Vites dokumentasjon sier at import.meta.env-konstanter erstattes statisk under bundling. Derfor, hvis lokal utvikling fungerer men produksjonsbundlen ikke gjør det, verifiser at VITE_SUPABASE_URL og VITE_SUPABASE_PUBLISHABLE_KEY eksisterte i bygge miljøet – ikke bare på maskinen som senere serverer de statiske filene.
Monorepos: sjekk hvilken katalog som faktisk er approten
Hvis Next.js- eller Vite-kommandoen kjører med apps/web som applikasjonsrot, kan en miljøfil plassert bare i repo/.env.local ikke være filen rammeverket laster. Vites envDir peker som standard til prosjektrøtten, og Next.js forventer sine .env*-filer på Next.js-prosjektrøtten.
Fiks: identifiser katalogen som inneholder applikasjonens package.json og rammeverkkonfigurasjon, og plasser env-filen der appen forventer den, eller konfigurer miljøkatalogen eksplisitt når rammeverket støtter det.
Supabase Edge Functions bruker forskjellige gjeldende standardvariabelnavn
Hvis feilen er inne i en Supabase Edge Function, ikke kopier blindt et Next.js- eller Vite-eksempel.
Merk at SUPABASE_PUBLISHABLE_KEYS og SUPABASE_SECRET_KEYS er flertall. Supabases migreringsguide forklarer at disse nye variablene inneholder JSON-objekter nøkkelt etter API-nøkkelnavnet. For en standard hemmelig nøkkel:
const secretKeys = JSON.parse(
Deno.env.get('SUPABASE_SECRET_KEYS') ?? '{}'
)
const secretKey = secretKeys['default']
if (!secretKey) {
throw new Error('Default Supabase secret key is missing')
}
Under migrasjonen kan eldre Edge Function-variabler som SUPABASE_ANON_KEY og SUPABASE_SERVICE_ROLE_KEY eksistere ved siden av de nye nøkkelordbøkene. Ikke anta at variabelnavnet fra en gammel funksjonsguide matcher den nye nøkkeltypen du nettopp opprettet.
Ikke løs feilen ved å eksponere en hemmelig nøkkel
En fristende “fiks” er å legge til NEXT_PUBLIC_ eller VITE_ til en serverhemmelighet slik at nettleseren endelig kan lese den. Det kan eliminere manglende-variabel-feilen mens det skaper et sikkerhetsproblem.
Supabases gjeldende API-nøkkelguide er eksplisitt:
Publishable key: ment for offentlige komponenter som nettleser- og mobilapplikasjoner.
Secret key: ment kun for backend-komponenter du kontrollerer; den omgår Row Level Security.
Hvis en hemmelig nøkkel har blitt eksponert i kildekode, en offentlig bundle, et skjermbilde eller et repository, fjern eller roter den gjennom Supabases API Keys-innstillinger i stedet for bare å endre navnet på miljøvariabelen.
Vanlige symptomer og den raskeste sjekken
Symptom
Mest sannsynlig sted å se
supabaseKey is required. umiddelbart ved oppstart
Det andre argumentet til createClient() er tomt eller undefined
Next.js fungerer på server men nøkkelen er undefined i en Client Component
Manglende NEXT_PUBLIC_-prefiks, feil navn, eller manglende byggetidsverdi
Vite viser undefined
Manglende VITE_-prefiks eller bruk av process.env i stedet for import.meta.env
Fungerer lokalt, feiler i produksjon
Hosting miljøvariabler, Production/Preview-omfang, eller manglende ombygging/omutplassering
Fungererte med ANON_KEY, ødelagt etter migrasjon
Kode og env-fil bruker forskjellige gamle/nye variabelnavn
Edge Function finner ikke SUPABASE_SECRET_KEY
Gjeldende Edge Function-standarder bruker SUPABASE_SECRET_KEYS som en JSON-ordbok
TypeScript kompilerer etter å ha lagt til ! men kjøretid feiler fortsatt
Assertjonen endret bare typen; miljøverdien er fortsatt manglende
Endelig egenkontroll: verifiser konfigurasjonen i riktig rekkefølge
Før du erklærer problemet løst, kjør denne sjekklisten:
Bekreft at Supabase Project URL kommer fra prosjektet du faktisk intenderte å bruke.
For nettleser/klientkode, bekreft at du bruker en gjeldende publishable nøkkel eller en fortsatt aktiv eldre anon-nøkkel – ikke en hemmelig nøkkel.
Bekreft at koden og miljøfilen bruker samme variabelnavn.
For Next.js klientkode, bruk NEXT_PUBLIC_* og direkte process.env.VARIABLE_NAME-referanser.
For Vite klientkode, bruk VITE_* og import.meta.env.VARIABLE_NAME.
Hold .env.local på applikasjonsroten i stedet for inne i /src.
Start utviklingsserveren på nytt etter redigering av miljøfiler.
For produksjon, sett verdiene i riktig utplasseringsmiljø og bygg/utplasser på nytt.
Ikke logg eller eksponer sb_secret_...-nøkler.
Fjern midlertidige feilsøkingslogger når konfigurasjonen er bekreftet.
Når createClient() initialiseres uten manglende-nøkkel-feilen, er miljøvariabelproblemet løst. Hvis den neste Supabase-forespørselen returnerer en autorisasjons-, Row Level Security- eller tabelltillatelsesfeil, behandle det som et separat problem. En gyldig API-nøkkel garanterer ikke at kalderen har lov til å lese eller endre hver rad; Supabase skiller bevisst API-nøkkelidentifikasjon fra brukerautentisering og databaseautorisasjon.
Den varige fiksen er ikke “endre navnet på nøkkelen til den fungerer”. Det er å justere fire ting: den gjeldende Supabase-nøkkeltypen, miljøvariabelnavnet, rammeverkets eksponeringsregler, og miljøet der appen faktisk bygges eller kjøres. Når disse er enige, mottar Supabase-klienten en ekte nøkkel i stedet for undefined, og den villedende konfigurasjonssløyfen tar slutt.