Kako riješiti problem Supabase API ključa koji nije pronađen u varijablama okruženja

Zadnja provjera: 11. rujna 2026. Dodate svoj Supabase URL i API ključ u .env datoteku, ponovno pokrenete aplikaciju i i dalje dobivate pogrešku poput “Supabase API key not found” ili Supabaseovu vlastitu pogrešku supabaseKey is required. U većini slučajeva ključ postoji negdje, ali kod koji poziva createClient() prima undefined ili prazan niz.

Iza mnogih zbunjujućih tutorijala stoji i važna promjena naziva iz 2026. godine. Supabase ukida naslijeđene anon i service_role API ključeve do kraja 2026. godine i sada preporučuje publishable (javne) ključeve za javni/klijentski kod te secret (tajne) ključeve za pouzdani serverski kod. Postojeći naslijeđeni ključevi mogu nastaviti raditi tijekom migracije dok ih ne onemogućite, ali naziv vaše varijable okruženja i vaš kod i dalje moraju savršeno odgovarati.

Trenutna Supabase dokumentacija koristi vrijednosti poput sb_publishable_... i sb_secret_.... Pogledajte službeni vodič za Supabase API ključeve i vodič za migraciju na publishable i secret ključeve.

Brzo rješenje: uskladite nazive varijabli s okvirom i kodom

Za trenutni Next.js preglednički klijent, Supabaseov službeni quickstart koristi:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

i:

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 || !supabaseKey) {
  throw new Error('Supabase environment variables are missing')
}

export const supabase = createClient(supabaseUrl, supabaseKey)

Za trenutni Vite/React preglednički klijent, Supabaseov službeni React quickstart koristi:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

a čitate ih pomoću:

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

Za serverski kod koji doista zahtijeva povišene pristupne ovlasti, Supabaseov vodič za API ključeve prikazuje obrazac poput:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SECRET_KEY=sb_secret_...

Nikada ne stavljajte sb_secret_... u varijablu koja je namjerno izložena pregledničkom kodu, poput Vite VITE_* varijable ili Next.js NEXT_PUBLIC_* varijable. Supabase navodi da tajni ključevi zaobilaze Row Level Security (sigurnost na razini retka) i moraju ostati u backend komponentama pod kontrolom developera.

Korak 1: potvrdite da vrijednost doista nedostaje tijekom izvršavanja

Nemojte započinjati regeneriranjem ključeva ili ponovnom instalacijom paketa. Prvo dokažite što vaša aplikacija prima.

Trenutni @supabase/supabase-js klijent provjerava drugi argument prosljeđen njegovom konstruktoru klijenta i baca supabaseKey is required. kada je ta vrijednost lažna (falsy). Ovo ponašanje možete vidjeti u službenom supabase-js izvornom kodu.

Dodajte privremenu zaštitu prije createClient():

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

console.log('Supabase URL loaded:', Boolean(supabaseUrl))
console.log('Supabase key loaded:', Boolean(supabaseKey))
console.log(
  'Key type:',
  supabaseKey?.startsWith('sb_publishable_') ? 'publishable' : 'other/missing'
)

if (!supabaseUrl || !supabaseKey) {
  throw new Error('Supabase environment variables are missing')
}

Za Vite koristite istu ideju s import.meta.env.

Nemojte ispisivati cijeli tajni ključ. Za otklanjanje pogrešaka dovoljan je boolean ili očekivani prefiks. Publishable ključ je dizajniran za javne komponente, ali bilježenje potpunih vjerodajnica i dalje je nepotrebno; tajni ključ nikada ne smije biti izložen u klijentskim zapisima (logs).

Također, imajte na umu da TypeScript sintaksa poput process.env.MY_KEY! ili process.env.MY_KEY as string ne stvara nedostajuću vrijednost tijekom izvršavanja. Ona samo mijenja ono što TypeScript vjeruje o tipu. Ako varijabla okruženja nije prisutna, Supabase i dalje prima undefined.

Samoprovjera: ako je boolean za ključ false, prestanite otklanjati pogreške u Supabase dopuštenjima, autentikaciji ili Row Level Security. Aplikacija još nije učitala konfiguraciju.

Korak 2: koristite trenutnu vrstu ključa—i uskladite stare i nove nazive

Otvorite dijaloški okvir Connect vašeg Supabase projekta ili idite na Settings → API Keys. Supabaseova trenutna dokumentacija izričito navodi Settings → API Keys kao mjesto za pregled svih API ključeva projekta.

Za kod koji se isporučuje u korisnikov preglednik, mobilnu aplikaciju, desktop aplikaciju ili drugu javnu komponentu, koristite publishable ključ. Supabase navodi da je publishable ključ sigurno izložiti jer je pristup bazi podataka i dalje kontroliran dodjelama prava (grants) i Row Level Security. Za backend komponente koje u potpunosti kontrolirate, secret ključ pruža povišene pristupne ovlasti i zaobilazi Row Level Security.

Migracija s naslijeđenih ključeva čest je izvor pogreške “not found” jer sljedeće kombinacije nisu ekvivalentne kao nazivi varijabli okruženja:

Starija varijabla poput NEXT_PUBLIC_SUPABASE_ANON_KEY nije automatski nevažeća. Ako vaš projekt i dalje ima aktivan naslijeđeni anon ključ i vaš kod čita tu točnu varijablu, ona može nastaviti raditi tijekom Supabaseovog razdoblja migracije. Problem nastaje kada kopirate novi publishable ključ u jedan naziv varijable, dok kod i dalje čita drugi.

Samoprovjera: pretražite svoj projekt za SUPABASE_. Usporedite svaki naziv varijable u kodu s točnim nazivima u vašim datotekama okruženja i postavkama implementacije. Ne oslanjajte se na pamćenje.

Korak 3: stavite .env datoteku tamo gdje je vaš okvir doista učitava

Točan ključ na pogrešnoj lokaciji datoteke efektivno je nedostajući ključ.

Next.js: držite .env datoteke u korijenu projekta

Next.js ima ugrađenu podršku za .env* datoteke. Njegov trenutni vodič za varijable okruženja kaže da, ako koristite /src direktorij, datoteke okruženja i dalje pripadaju u korijen projekta, a ne unutar /src. Pogledajte službeni Next.js vodič za varijable okruženja.

Tipičan raspored je:

my-app/
  .env.local
  package.json
  next.config.js
  app/
  src/        # if used

Za kod na strani preglednika, Next.js izlaže samo varijable koje koriste NEXT_PUBLIC_ prefiks. Te se vrijednosti ugrađuju (inline) u preglednički bundle tijekom izgradnje (build time).

Vite: koristite VITE_ i import.meta.env

Vite izlaže klijentske varijable okruženja putem import.meta.env. Po defaultu, samo nazivi s prefiksom VITE_ izloženi su klijentskom kodu. Službeni Vite vodič za varijable okruženja i načine rada to izravno dokumentira.

Ovo će raditi u Vite klijentu:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

const url = import.meta.env.VITE_SUPABASE_URL
const key = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY

Ovo će obično biti undefined u Vite pregledničkom kodu:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

jer mu nedostaje defaultni VITE_ prefiks za izlaganje.

Node/serverski kod: nemojte slijepo kopirati prefikse preglednika

Serverski kod obično čita iz process.env. Ako ključ ne mora biti dostupan u pregledniku, nemojte dodavati javni prefiks samo da bi bio vidljiv. Supabase izričito upozorava da su tajni ključevi isključivo za backend.

Samoprovjera: provjerite tri stvari zajedno: je li env datoteka u korijenu aplikacije, koristi li naziv varijable ispravan prefiks okvira i koristi li kod ispravan pristupnik okvira—process.env za Next.js/Node ili import.meta.env za Vite klijentski kod.

Korak 4: ponovno pokrenite razvoj poslužitelj nakon promjene datoteka okruženja

Varijable okruženja obično se učitavaju kada se razvojni proces pokrene. Vite izričito dokumentira da se .env datoteke učitavaju pri pokretanju i da biste trebali ponovno pokrenuti poslužitelj nakon promjena.

Zaustavite trenutni proces i pokrenite ga ponovno:

# Next.js
npm run dev

# Vite
npm run dev

Ako se pogreška pojavila tek nakon što ste stvorili datoteku okruženja dok je poslužitelj već bio pokrenut, ponovno pokretanje može biti cijelo rješenje.

Samoprovjera: ponovno pokrenite privremene boolean provjere. Ako su vrijednosti sada učitane, uklonite nepotrebne izlaze za otklanjanje pogrešaka i nastavite s normalnim Supabase radom.

Koristite zaštitu tijekom izvršavanja umjesto skrivanja problema s TypeScriptom

Korisni obrazac za produkciju je neuspjeh s jasnom porukom o konfiguraciji prije pozivanja Supabasea:

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)

Ovo je bolje od:

createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
)

kada otklanjate pogreške, jer ne-null asertcija može sakriti TypeScript upozorenje bez promjene vrijednosti tijekom izvršavanja.

Ako radi lokalno, ali ne uspijeva nakon implementacije

Ovo je obično problem okruženja implementacije, a ne problem Supabase projekta.

Lokalne .env.local datoteke obično se ne commitaju u Git—i ne bi ih trebalo tretirati kao mehanizam za isporuku tajni u produkciji. Konfigurirajte iste nazive varijabli u postavkama projekta vašeg hosting pružatelja.

Na primjer, Vercel dokumentira odvojena okruženja Production, Preview i Development. Također navodi da se promjene varijabli okruženja primjenjuju samo na nove implementacije, pa morate ponovno implementirati nakon što ih dodate ili promijenite. Pogledajte Vercelov službeni vodič za upravljanje varijablama okruženja.

Provjerite:

• Je li varijabla definirana za Production, a ne samo za Preview?
• Odgovara li naziv točno kodu?
• Je li stvorena nova implementacija nakon što je varijabla dodana?
• Je li javna varijabla bila prisutna kada je klijentski bundle izgrađen?

Next.js javne varijable su vrijednosti tijekom izgradnje

Next.js dokumentira da se NEXT_PUBLIC_* varijable ugrađuju (inline) u preglednički JavaScript tijekom izgradnje (build time). Nakon što je aplikacija izgrađena, promjena okruženja tijekom izvršavanja ne prepisuje te vrijednosti u postojećem klijentskom bundleu. Ako izgradite Docker sliku bez NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY i kasnije je ubacite samo kada se kontejner pokrene, preglednički kod i dalje može sadržavati nedostajuću vrijednost iz vremena izgradnje.

Rješenje: osigurajte javne Supabase vrijednosti tijekom izgradnje koja proizvodi klijentski bundle ili preoblikujte aplikaciju da pruža konfiguraciju tijekom izvršavanja putem mehanizma pod kontrolom poslužitelja.

Vite također zamjenjuje klijentske env vrijednosti tijekom izgradnje

Viteova dokumentacija kaže da se import.meta.env konstante statički zamjenjuju tijekom pakiranja (bundling). Stoga, ako lokalni razvoj radi, ali produkcijski bundle ne, provjerite jesu li VITE_SUPABASE_URL i VITE_SUPABASE_PUBLISHABLE_KEY postojali u okruženju izgradnje—a ne samo na stroju koji kasnije poslužuje statičke datoteke.

Monorepos: provjerite koji je direktorij zapravo korijen aplikacije

Monorepo može sadržavati:

repo/
  package.json
  apps/
    web/
      package.json
      .env.local
      app/
  packages/
    ui/

Ako se Next.js ili Vite naredba pokreće s apps/web kao korijenom aplikacije, datoteka okruženja postavljena samo na repo/.env.local možda nije datoteka koju okvir učitava. Viteov envDir po defaultu je korijen projekta, a Next.js očekuje svoje .env* datoteke u korijenu Next.js projekta.

Rješenje: identificirajte direktorij koji sadrži aplikacijski package.json i konfiguraciju okvira, zatim stavite env datoteku tamo gdje ta aplikacija očekuje ili eksplicitno konfigurirajte direktorij okruženja kada okvir to podržava.

Supabase Edge Functions koriste različite trenutne defaultne nazive varijabli

Ako je pogreška unutar Supabase Edge Function, nemojte slijepo kopirati Next.js ili Vite primjer.

Supabaseova trenutna dokumentacija o varijablama okruženja za Edge Functions navodi ove defaultne tajne, između ostalih:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Primijetite da su SUPABASE_PUBLISHABLE_KEYS i SUPABASE_SECRET_KEYS u množini. Supabaseov vodič za migraciju objašnjava da ove nove varijable sadrže JSON objekte ključane po nazivu API ključa. Za defaultni tajni ključ:

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')
}

Tijekom migracije, naslijeđene Edge Function varijable poput SUPABASE_ANON_KEY i SUPABASE_SERVICE_ROLE_KEY mogu postojati uz nove rječnike ključeva. Nemojte pretpostavljati da naziv varijable iz starog tutorijala za funkcije odgovara novoj vrsti ključa koju ste upravo stvorili.

Nemojte riješiti pogrešku izlaganjem tajnog ključa

Iskušenje “rješenje” je dodati NEXT_PUBLIC_ ili VITE_ serverskoj tajni kako bi je preglednik konačno mogao pročitati. To može eliminirati pogrešku nedostajuće varijable, ali stvoriti sigurnosni problem.

Supabaseov trenutni vodič za API ključeve je izričit:

• Publishable ključ: namijenjen javnim komponentama poput pregledničkih i mobilnih aplikacija.
• Secret ključ: namijenjen isključivo backend komponentama koje kontrolirate; zaobilazi Row Level Security.

Ako je tajni ključ izložen u izvornom kodu, javnom bundleu, snimci zaslona ili repozitoriju, uklonite ili rotirajte ga putem Supabaseovih postavki API ključeva umjesto da samo preimenujete varijablu okruženja.

Uobičajeni simptomi i najbrža provjera

Konačna samoprovjera: potvrdite konfiguraciju ispravnim redoslijedom

Prije nego što proglasite problem riješenim, provedite ovaj popis provjera:

1. Potvrdite da Supabase Project URL dolazi iz projekta koji stvarno namjeravate koristiti.
2. Za klijentski kod u pregledniku, potvrdite da koristite trenutni publishable ključ ili još uvijek aktivan naslijeđeni anon ključ—ne tajni ključ.
3. Potvrdite da kod i datoteka okruženja koriste iste nazive varijabli.
4. Za Next.js klijentski kod, koristite NEXT_PUBLIC_* i izravne reference process.env.VARIABLE_NAME.
5. Za Vite klijentski kod, koristite VITE_* i import.meta.env.VARIABLE_NAME.
6. Držite .env.local u korijenu aplikacije, a ne unutar /src.
7. Ponovno pokrenite razvoj poslužitelj nakon uređivanja datoteka okruženja.
8. Za produkciju, postavite vrijednosti u ispravno okruženje implementacije i ponovno izgradite/reimplementirajte.
9. Nemojte bilježiti ili izlagati sb_secret_... ključeve.
10. Uklonite privremene debug zapise kada je konfiguracija potvrđena.

Kada se createClient() inicijalizira bez pogreške nedostajućeg ključa, problem s varijablama okruženja je riješen. Ako sljedeći Supabase zahtjev vrati pogrešku autorizacije, Row Level Security ili dopuštenja za tablicu, tretirajte to kao zaseban problem. Važeći API ključ ne jamči da pozivatelju smije čitati ili mijenjati svaki redak; Supabase namjerno odvaja identifikaciju API ključa od korisničke autentikacije i autorizacije baze podataka.

Trajno rješenje nije “preimenuj ključ dok ne radi”. To je usklađivanje četiri stvari: trenutne vrste Supabase ključa, naziva varijable okruženja, pravila izlaganja okvira i okruženja u kojem se aplikacija stvarno gradi ili izvršava. Kada se te stvari usklade, Supabase klijent prima stvarni ključ umjesto undefined, a zavaravajuća petlja konfiguracije završava.