Ako opraviť chybu „Supabase API Key Not Found“ v premenných prostredia

Naposledy overené: 11. septembra 2026. Pridáte URL adresu Supabase a kľúč API do súboru .env, reštartujete aplikáciu a stále dostávate chybu ako „Supabase API key not found“ alebo vlastnú chybu Supabase supabaseKey is required. Vo väčšine prípadov kľúč niekde existuje, ale kód, ktorý volá createClient(), dostáva hodnotu undefined alebo prázdny reťazec.

Za mnohými mätúcimi tutoriálmi stojí aj dôležitá zmena v pomenovaní z roku 2026. Supabase do konca roka 2026 zastaráva staršie kľúče API anon a service_role a teraz odporúča používať publishable (verejné) kľúče pre verejný/klientský kód a secret (tajné) kľúče pre dôveryhodný serverový kód. Existujúce staršie kľúče môžu počas migrácie fungovať, kým ich nevypnete, ale názov vašej premennej prostredia a váš kód sa musia stále presne zhodovať.

Aktuálna dokumentácia Supabase používa hodnoty ako sb_publishable_... a sb_secret_.... Pozrite si oficiálnu príručku kľúčov API Supabase a príručku migrácie na publishable a secret kľúče.

Rýchla oprava: zosúlaďte názvy premenných s frameworkom a kódom

Pre aktuálny prehliadačový klient Next.js používa oficiálny rýchly štart Supabase:

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

a:

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)

Pre aktuálny prehliadačový klient Vite/React používa oficiálny rýchly štart Supabase pre React:

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

a načítate ich pomocou:

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

Pre server-only kód, ktorý skutočne potrebuje zvýšený prístup, ukazuje príručka kľúčov API Supabase vzor ako:

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

Nikdy nedávajte sb_secret_... do premennej, ktorá je zámerne vystavená prehliadačovému kódu, ako je premenná Vite VITE_* alebo premenná Next.js NEXT_PUBLIC_*. Supabase uvádza, že tajné kľúče obchádzajú zabezpečenie na úrovni riadkov (Row Level Security) a musia zostať v backendových komponentách kontrolovaných vývojárom.

Krok 1: potvrďte, že hodnota skutočne chýba za behu

Nezačínajte regenerovaním kľúčov alebo preinštalovaním balíčkov. Najprv dokážte, čo vaša aplikácia prijíma.

Aktuálny klient @supabase/supabase-js kontroluje druhý argument odovzdaný konštruktoru klienta a vyvolá chybu supabaseKey is required., keď je táto hodnota falsy. Toto správanie môžete vidieť v oficiálnom zdrojovom kóde supabase-js.

Pridajte dočasnú kontrolu pred 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')
}

Pre Vite použite rovnaký nápad s import.meta.env.

Nevytlačte celý tajný kľúč. Na ladenie stačí boolean alebo očakávaný prefix. Publishable kľúč je určený pre verejné komponenty, ale logovanie úplných prihlasovacích údajov je stále zbytočné; tajný kľúč sa nikdy nesmie objaviť v klientskych logoch.

Všimnite si tiež, že syntax TypeScriptu ako process.env.MY_KEY! alebo process.env.MY_KEY as string nevytvára chýbajúcu hodnotu za behu. Len mení to, čo si TypeScript myslí o type. Ak premenná prostredia chýba, Supabase stále dostáva undefined.

Samokontrola: ak je boolean pre kľúč false, prestaňte ladiť povolenia Supabase, autentifikáciu alebo zabezpečenie na úrovni riadkov. Aplikácia ešte nenahrala konfiguráciu.

Krok 2: použite aktuálny typ kľúča – a zosúlaďte staré a nové názvy

Otvorte dialógové okno Connect vo vašom projekte Supabase alebo prejdite na Settings → API Keys. Aktuálna dokumentácia Supabase explicitne uvádza Settings → API Keys ako miesto, kde si môžete prezrieť všetky kľúče API projektu.

Pre kód, ktorý sa dodáva do prehliadača používateľa, mobilnej aplikácie, desktopovej aplikácie alebo inej verejnej komponenty, použite publishable kľúč. Supabase uvádza, že publishable kľúč je bezpečné vystaviť, pretože prístup k databáze je stále kontrolovaný prostredníctvom oprávnení a zabezpečenia na úrovni riadkov. Pre backendové komponenty, ktoré plne kontrolujete, poskytuje secret kľúč zvýšený prístup a obchádza zabezpečenie na úrovni riadkov.

Migrácia zo starších kľúčov je bežným zdrojom chyby „not found“, pretože nasledujúce kombinácie nie sú ekvivalentné ako názvy premenných prostredia:

Staršia premenná ako NEXT_PUBLIC_SUPABASE_ANON_KEY nie je automaticky neplatná. Ak váš projekt stále má aktívny starší kľúč anon a váš kód číta presne túto premennú, môže počas obdobia migrácie Supabase naďalej fungovať. Problémom je skopírovanie nového publishable kľúča do jedného názvu premennej, zatiaľ čo kód stále číta inú.

Samokontrola: vyhľadajte vo svojom projekte SUPABASE_. Porovnajte každý názov premennej v kóde s presnými názvami vo vašich súboroch prostredia a nastaveniach nasadenia. Nespoliehajte sa na pamäť.

Krok 3: umiestnite súbor .env tam, kde ho váš framework skutočne načítava

Správny kľúč na nesprávnom mieste je efektívne chýbajúci kľúč.

Next.js: ponechajte súbory .env v koreni projektu

Next.js má vstavanú podporu pre súbory .env*. Jeho aktuálna príručka premenných prostredia hovorí, že ak používate adresár /src, súbory prostredia stále patria do koreňa projektu, nie dovnútra /src. Pozrite si oficiálnu príručku premenných prostredia Next.js.

Typické rozloženie je:

my-app/
  .env.local
  package.json
  next.config.js
  app/
  src/        # ak sa používa

Pre kód na strane prehliadača Next.js vystavuje iba premenné, ktoré používajú prefix NEXT_PUBLIC_. Tieto hodnoty sú vstavané do bundle prehliadača v čase zostavenia (build time).

Vite: použite VITE_ a import.meta.env

Vite vystavuje klientske premenné prostredia prostredníctvom import.meta.env. Štandardne sú vystavené klientskemu kódu iba názvy s prefixom VITE_. Oficiálna príručka Vite Env Variables and Modes to dokumentuje priamo.

Toto bude fungovať v klientskom kóde Vite:

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

Toto bude v prehliadačovom kóde Vite zvyčajne undefined:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

pretože mu chýba štandardný prefix vystavenia VITE_.

Node/serverový kód: nekopírujte slepo prefixy pre prehliadač

Serverový kód zvyčajne číta z process.env. Ak kľúč nemusí byť dostupný v prehliadači, nepridávajte verejný prefix len preto, aby bol viditeľný. Supabase konkrétne varuje, že tajné kľúče sú určené iba pre backend.

Samokontrola: overte tri veci naraz: súbor env je v koreni aplikácie, názov premennej používa správny prefix frameworku a kód používa správny prístupový objekt frameworku – process.env pre Next.js/Node alebo import.meta.env pre klientský kód Vite.

Krok 4: reštartujte vývojový server po zmene súborov prostredia

Premenné prostredia sa zvyčajne načítavajú pri spustení vývojového procesu. Vite explicitne dokumentuje, že súbory .env sa načítavajú pri štarte a že po zmenách by ste mali server reštartovať.

Zastavte aktuálny proces a spustite ho znova:

# Next.js
npm run dev

# Vite
npm run dev

Ak sa chyba objavila až po vytvorení súboru prostredia, keď už bol server spustený, reštart môže byť celá oprava.

Samokontrola: znova spustite dočasné boolean kontroly. Ak sú hodnoty teraz načítané, odstráňte nepotrebný ladiaci výstup a pokračujte v bežnej prevádzke Supabase.

Použite runtime guard namiesto maskovania problému pomocou TypeScriptu

Užitočným produkčným vzorom je zlyhať s jasnou konfiguračnou správou pred volaním 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)

Toto je lepšie než:

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

keď riešite problémy, pretože non-null asertácia môže skryť varovanie TypeScriptu bez zmeny hodnoty za behu.

Ak to funguje lokálne, ale zlyhá po nasadení

Toto je zvyčajne problém s prostredím nasadenia, nie s projektom Supabase.

Lokálne súbory .env.local sa zvyčajne neodosielajú do Gitu – a nemali by sa považovať za mechanizmus dodávania produkčných tajomstiev. Nakonfigurujte rovnaké názvy premenných v nastaveniach projektu vášho hostingového poskytovateľa.

Napríklad Vercel dokumentuje samostatné prostredia Production, Preview a Development. Tiež uvádza, že zmeny premenných prostredia sa aplikujú iba na nové nasadenia, takže po ich pridaní alebo zmene musíte znova nasadiť. Pozrite si oficiálnu príručku správy premenných prostredia Vercel.

Skontrolujte:

• Je premenná definovaná pre Production, nie len pre Preview?
• Zodpovedá názov presne kódu?
• Bolo po pridaní premennej vytvorené nové nasadenie?
• Bola verejná premenná prítomná pri zostavení bundle klienta?

Verejné premenné Next.js sú hodnoty v čase zostavenia

Next.js dokumentuje, že premenné NEXT_PUBLIC_* sú vstavané do JavaScriptu prehliadača v čase zostavenia. Po zostavení aplikácie zmena runtime prostredia neprepíše tieto hodnoty v existujúcom bundle klienta. Ak zostavíte Docker image bez NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY a neskôr ho vložíte až pri štarte kontajnera, kód prehliadača môže stále obsahovať chýbajúcu hodnotu z času zostavenia.

Oprava: poskytnite verejné hodnoty Supabase počas zostavenia, ktoré vytvára bundle klienta, alebo preprojektujte aplikáciu tak, aby poskytovala runtime konfiguráciu prostredníctvom mechanizmu riadeného serverom.

Vite tiež nahrádza klientske hodnoty env počas zostavenia

Dokumentácia Vite hovorí, že konštanty import.meta.env sú staticky nahradené počas bundlovania. Preto, ak lokálny vývoj funguje, ale produkčný bundle nie, overte, či VITE_SUPABASE_URL a VITE_SUPABASE_PUBLISHABLE_KEY existovali v prostredí zostavenia – nielen na stroji, ktorý neskôr obsluhuje statické súbory.

Monorepá: skontrolujte, ktorý adresár je skutočne koreňom aplikácie

Monorepá môže obsahovať:

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

Ak sa príkaz Next.js alebo Vite spúšťa s apps/web ako koreňom aplikácie, súbor prostredia umiestnený iba v repo/.env.local nemusí byť súbor, ktorý framework načítava. Predvolená hodnota envDir pre Vite je koreň projektu a Next.js očakáva svoje súbory .env* v koreni projektu Next.js.

Oprava: identifikujte adresár obsahujúci package.json a konfiguráciu frameworku aplikácie, potom umiestnite súbor env tam, kde ho daná aplikácia očakáva, alebo explicitne nakonfigurujte adresár prostredia, ak to framework podporuje.

Supabase Edge Functions používajú iné aktuálne predvolené názvy premenných

Ak je chyba vnútri Supabase Edge Function, neslepo nekopírujte príklad Next.js alebo Vite.

Aktuálna dokumentácia premenných prostredia Edge Functions Supabase uvádza medzi inými tieto predvolené tajné kľúče:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Všimnite si, že SUPABASE_PUBLISHABLE_KEYS a SUPABASE_SECRET_KEYS sú v množnom čísle. Príručka migrácie Supabase vysvetľuje, že tieto nové premenné obsahujú JSON objekty kľúčované podľa názvu kľúča API. Pre predvolený tajný kľúč:

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

Počas migrácie môžu staršie premenné Edge Function ako SUPABASE_ANON_KEY a SUPABASE_SERVICE_ROLE_KEY existovať vedľa nových slovníkov kľúčov. Nepredpokladajte, že názov premennej zo starého tutoriálu funkcie zodpovedá novému typu kľúča, ktorý ste práve vytvorili.

Neriešte chybu vystavením tajného kľúča

Lákavá „oprava“ je pridať NEXT_PUBLIC_ alebo VITE_ k serverovému tajnému kľúču, aby ho prehliadač mohol konečne čítať. To môže odstrániť chybu chýbajúcej premennej, ale vytvoriť bezpečnostný problém.

Aktuálna príručka kľúčov API Supabase je explicitná:

• Publishable kľúč: určený pre verejné komponenty, ako sú prehliadačové a mobilné aplikácie.
• Secret kľúč: určený iba pre backendové komponenty, ktoré kontrolujete; obchádza zabezpečenie na úrovni riadkov.

Ak bol tajný kľúč vystavený v zdrojovom kóde, verejnom bundle, snímke obrazovky alebo repozitári, odstráňte ho alebo rotujte prostredníctvom nastavení API Keys v Supabase namiesto jednoduchého premenovania premennej prostredia.

Bežné príznaky a najrýchlejšia kontrola

Finálna samokontrola: overte konfiguráciu v správnom poradí

Pred vyhlásením, že je problém vyriešený, spustite tento kontrolný zoznam:

1. Potvrďte, že Project URL Supabase pochádza z projektu, ktorý skutočne chcete používať.
2. Pre klientský kód v prehliadači potvrďte, že používate aktuálny publishable kľúč alebo stále aktívny starší kľúč anon – nie tajný kľúč.
3. Potvrďte, že kód a súbor prostredia používajú rovnaké názvy premenných.
4. Pre klientský kód Next.js použite NEXT_PUBLIC_* a priame odkazy process.env.NÁZOV_PREMENNEJ.
5. Pre klientský kód Vite použite VITE_* a import.meta.env.NÁZOV_PREMENNEJ.
6. Ponechajte .env.local v koreni aplikácie, nie vo vnútri /src.
7. Po úprave súborov prostredia reštartujte vývojový server.
8. Pre produkciu nastavte hodnoty v správnom prostredí nasadenia a znovuzostavte/znovunasadte.
9. Nelogujte ani nevystavujte kľúče sb_secret_....
10. Odstráňte dočasné ladiace logy, keď je konfigurácia potvrdená.

Keď sa createClient() inicializuje bez chyby chýbajúceho kľúča, problém s premennými prostredia je vyriešený. Ak ďalšia požiadavka Supabase vráti chybu autorizácie, zabezpečenia na úrovni riadkov alebo povolenia k tabuľke, považujte to za samostatný problém. Platný kľúč API nezaručuje, že volajúci má povolenie čítať alebo upravovať každý riadok; Supabase zámerne oddeľuje identifikáciu kľúča API od autentifikácie používateľa a autorizácie databázy.

Trvalá oprava nie je „premenovať kľúč, kým to nebude fungovať“. Ide o zosúladenie štyroch vecí: aktuálneho typu kľúča Supabase, názvu premennej prostredia, pravidiel vystavenia frameworku a prostredia, v ktorom je aplikácia skutočne zostavená alebo vykonávaná. Keď sa tieto zhodujú, klient Supabase dostane skutočný kľúč namiesto undefined a zavádzajúca konfiguračná slučka sa skončí.