Jak opravit chybu „Supabase API Key Not Found“ v proměnných prostředí

Naposledy ověřeno: 11. září 2026. Přidáte URL a API klíč Supabase do souboru .env, restartujete aplikaci a stále obdržíte chybu jako „Supabase API key not found“ nebo vlastní chybu Supabase supabaseKey is required. Ve většině případů klíč někde existuje, ale kód volající createClient() obdrží hodnotu undefined nebo prázdný řetězec.

Za mnoha matoucími tutoriály se také skrývá důležitá změna názvosloví z roku 2026. Supabase do konce roku 2026 vyřazuje starší API klíče anon a service_role a nyní doporučuje používat publishable (publikovatelné) klíče pro veřejný/klientský kód a secret (tajné) klíče pro důvěryhodný serverový kód. Existující starší klíče mohou během migrace fungovat, dokud je nevypnete, ale název vaší proměnné prostředí a váš kód se musí stále přesně shodovat.

Aktuální dokumentace Supabase používá hodnoty jako sb_publishable_... a sb_secret_.... Podívejte se na oficiální průvodce API klíči Supabase a průvodce migrací na publikovatelné a tajné klíče.

Rychlá oprava: zajistěte, aby názvy proměnných odpovídaly frameworku a kódu

Pro aktuální prohlížečový klient Next.js používá oficiální rychlý start 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)

Pro aktuální prohlížečový klient Vite/React používá oficiální rychlý start Reactu pro Supabase:

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

a načítáte je pomocí:

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

Pro kód pouze na serveru, který skutečně potřebuje zvýšená oprávnění, ukazuje průvodce API klíči Supabase vzor jako:

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

Nikdy nedávejte sb_secret_... do proměnné, která je záměrně vystavena kódu v prohlížeči, jako je proměnná Vite VITE_* nebo proměnná Next.js NEXT_PUBLIC_*. Supabase uvádí, že tajné klíče obcházejí zabezpečení na úrovni řádků (Row Level Security) a musí zůstat v backendových komponentách kontrolovaných vývojáři.

Krok 1: potvrďte, že hodnota skutečně chybí za běhu

Nezačínejte regenerací klíčů nebo přeinstalováním balíčků. Nejprve prokažte, co vaše aplikace obdrží.

Aktuální klient @supabase/supabase-js kontroluje druhý argument předaný konstruktoru klienta a vyhazuje chybu supabaseKey is required., když je tato hodnota nepravdivá (falsy). Toto chování můžete vidět v oficiálním zdroji supabase-js.

Přidejte dočasnou kontrolu před 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')
}

Pro Vite použijte stejný princip s import.meta.env.

Nevypisujte celý tajný klíč. Pro ladění stačí boolean nebo očekávaný prefix. Publikovatelný klíč je určen pro veřejné komponenty, ale logování kompletních přihlašovacích údajů je stále zbytečné; tajný klíč nikdy nesmí být vystaven v logách klienta.

Všimněte si také, že syntaxe TypeScriptu jako process.env.MY_KEY! nebo process.env.MY_KEY as string nevytvoří chybějící hodnotu za běhu. Pouze změní to, co si TypeScript myslí o typu. Pokud proměnná prostředí chybí, Supabase stále obdrží undefined.

Sebekontrola: pokud je boolean pro klíč false, přestaňte ladit oprávnění Supabase, autentizaci nebo zabezpečení na úrovni řádků. Aplikace ještě nenačetla konfiguraci.

Krok 2: použijte aktuální typ klíče – a zajistěte konzistenci starých a nových názvů

Otevřete dialog Connect ve vašem projektu Supabase nebo přejděte do Settings → API Keys. Aktuální dokumentace Supabase explicitně uvádí Settings → API Keys jako místo pro zobrazení všech API klíčů projektu.

Pro kód, který je dodáván do prohlížeče uživatele, mobilní aplikace, desktopové aplikace nebo jiné veřejné komponenty, použijte publishable klíč. Supabase uvádí, že publikovatelný klíč je bezpečné vystavit, protože přístup k databázi je stále řízen granty a zabezpečením na úrovni řádků. Pro backendové komponenty, které plně kontrolujete, poskytuje secret klíč zvýšená oprávnění a obchází zabezpečení na úrovni řádků.

Migrace ze starších klíčů je běžným zdrojem chyby „not found“, protože následující kombinace nejsou jako názvy proměnných prostředí ekvivalentní:

Starší proměnná jako NEXT_PUBLIC_SUPABASE_ANON_KEY není automaticky neplatná. Pokud váš projekt stále má aktivní starší klíč anon a váš kód čte přesně tuto proměnnou, může během migračního období Supabase stále fungovat. Problémem je zkopírování nového publikovatelného klíče do jedné proměnné, zatímco kód stále čte jinou.

Sebekontrola: vyhledejte ve svém projektu SUPABASE_. Porovnejte každý název proměnné v kódu s přesnými názvy ve vašich souborech prostředí a nastaveních nasazení. Nespoléhejte na paměť.

Krok 3: umístěte soubor .env tam, kde ho váš framework skutečně načítá

Správný klíč ve špatném umístění souboru je efektivně chybějící klíč.

Next.js: ponechte soubory .env v kořeni projektu

Next.js má vestavěnou podporu pro soubory .env*. Jeho aktuální průvodce proměnnými prostředí uvádí, že pokud používáte adresář /src, soubory prostředí stále patří do kořene projektu, nikoli dovnitř /src. Podívejte se na oficiální průvodce proměnnými prostředí Next.js.

Typické rozložení je:

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

Pro kód na straně prohlížeče Next.js vystavuje pouze proměnné, které používají prefix NEXT_PUBLIC_. Tyto hodnoty jsou vloženy do bundle prohlížeče v době sestavení (build time).

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

Vite vystavuje proměnné prostředí klienta prostřednictvím import.meta.env. Ve výchozím nastavení jsou vystaveny klientskému kódu pouze názvy s prefixem VITE_. Oficiální průvodce proměnnými prostředí a režimy Vite to dokumentuje přímo.

Toto bude fungovat v klientu 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 kódu prohlížeče Vite obvykle undefined:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

protože mu chybí výchozí prefix vystavení VITE_.

Kód Node/server: nekopírujte slepě prefixy prohlížeče

Serverový kód obvykle čte z process.env. Pokud klíč nemusí být dostupný v prohlížeči, nepřidávejte veřejný prefix jen proto, aby byl viditelný. Supabase specificky varuje, že tajné klíče jsou pouze pro backend.

Sebekontrola: ověřte tři věci současně: soubor env je v kořeni aplikace, název proměnné používá správný prefix frameworku a kód používá správný přístupor frameworku – process.env pro Next.js/Node nebo import.meta.env pro klientský kód Vite.

Krok 4: restartujte vývojový server po změně souborů prostředí

Proměnné prostředí se běžně načítají při spuštění vývojového procesu. Vite explicitně dokumentuje, že soubory .env se načítají při startu a že byste měli po změnách restartovat server.

Zastavte aktuální proces a spusťte ho znovu:

# Next.js
npm run dev

# Vite
npm run dev

Pokud se chyba objevila až poté, co jste vytvořili soubor prostředí, zatímco server již běžel, restart může být celá oprava.

Sebekontrola: znovu spusťte dočasné boolean kontroly. Pokud jsou hodnoty nyní načteny, odstraňte nepotřebné ladicí výstupy a pokračujte k normálnímu provozu Supabase.

Použijte kontrolu za běhu místo skrývání problému pomocí TypeScriptu

Užitečným vzorem pro produkci je selhat s jasnou konfigurační zprávou před volání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)

To je lepší než:

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

při řešení problémů, protože non-null assertion může skrýt varování TypeScriptu bez změny hodnoty za běhu.

Pokud funguje lokálně, ale selhává po nasazení

To je obvykle problém prostředí nasazení, nikoli problém projektu Supabase.

Lokální soubory .env.local se obvykle neodesílají do Gitu – a neměly by být považovány za mechanismus dodávání produkčních tajemství. Nastavte stejné názvy proměnných v nastavení projektu vašeho hostingového poskytovatele.

Například Vercel dokumentuje oddělená prostředí Production, Preview a Development. Také uvádí, že změny proměnných prostředí se aplikují pouze na nová nasazení, takže po jejich přidání nebo změně musíte znovu nasadit. Podívejte se na oficiální průvodce správou proměnných prostředí Vercel.

Zkontrolujte:

• Je proměnná definována pro Production, nikoli pouze pro Preview?
• Odpovídá název přesně kódu?
• Bylo po přidání proměnné vytvořeno nové nasazení?
• Byla veřejná proměnná přítomna při sestavení bundle klienta?

Veřejné proměnné Next.js jsou hodnoty v době sestavení

Next.js dokumentuje, že proměnné NEXT_PUBLIC_* jsou vloženy do JavaScriptu prohlížeče v době sestavení. Po sestavení aplikace změna prostředí za běhu nepřepíše tyto hodnoty v existujícím bundle klienta. Pokud sestavíte Docker image bez NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY a později ji vložíte pouze při spuštění kontejneru, kód prohlížeče může stále obsahovat chybějící hodnotu z doby sestavení.

Oprava: poskytněte veřejné hodnoty Supabase během sestavení, které vytváří bundle klienta, nebo přepracujte aplikaci tak, aby poskytovala konfiguraci za běhu prostřednictvím mechanismu řízeného serverem.

Vite také nahrazuje hodnoty prostředí klienta během sestavení

Dokumentace Vite uvádí, že konstanty import.meta.env jsou staticky nahrazeny během bundlování. Pokud tedy lokální vývoj funguje, ale produkční bundle ne, ověřte, že VITE_SUPABASE_URL a VITE_SUPABASE_PUBLISHABLE_KEY existovaly v prostředí sestavení – nikoli pouze na stroji, který později obsluhuje statické soubory.

Monorepos: zkontrolujte, který adresář je skutečně kořenem aplikace

Monorepo může obsahovat:

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

Pokud se příkaz Next.js nebo Vite spouští s apps/web jako kořenem aplikace, soubor prostředí umístěný pouze v repo/.env.local nemusí být soubor, který framework načítá. envDir Vite ve výchozím nastavení ukazuje na kořen projektu a Next.js očekává své soubory .env* v kořeni projektu Next.js.

Oprava: identifikujte adresář obsahující package.json aplikace a konfiguraci frameworku, poté umístěte soubor env tam, kde ho tato aplikace očekává, nebo explicitně nakonfigurujte adresář prostředí, pokud to framework podporuje.

Edge Functions Supabase používají jiné aktuální výchozí názvy proměnných

Pokud je chyba uvnitř Edge Function Supabase, neslepujte příklady pro Next.js nebo Vite.

Aktuální dokumentace proměnných prostředí Edge Functions Supabase uvádí mezi jinými tyto výchozí tajné klíče:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Všimněte si, že SUPABASE_PUBLISHABLE_KEYS a SUPABASE_SECRET_KEYS jsou v množném čísle. Migrační průvodce Supabase vysvětluje, že tyto nové proměnné obsahují JSON objekty klíčované podle názvu API klíče. Pro výchozí tajný klíč:

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

Během migrace mohou starší proměnné Edge Function jako SUPABASE_ANON_KEY a SUPABASE_SERVICE_ROLE_KEY existovat vedle nových slovníků klíčů. Nepředpokládejte, že název proměnné ze starého tutoriálu funkcí odpovídá novému typu klíče, který jste právě vytvořili.

Neřešte chybu vystavením tajného klíče

Lákavá „oprava“ je přidat NEXT_PUBLIC_ nebo VITE_ k serverovému tajemství, aby ho prohlížeč mohl konečně přečíst. To může eliminovat chybu chybějící proměnné, ale vytvořit bezpečnostní problém.

Aktuální průvodce API klíči Supabase je explicitní:

• Publikovatelný klíč: určen pro veřejné komponenty, jako jsou aplikace v prohlížeči a mobilní aplikace.
• Tajný klíč: určen pouze pro backendové komponenty, které kontrolujete; obchází zabezpečení na úrovni řádků.

Pokud byl tajný klíč vystaven ve zdrojovém kódu, veřejném bundle, snímku obrazovky nebo repozitáři, odstraňte jej nebo rotujte prostřednictvím nastavení API Keys v Supabase, místo pouhého přejmenování proměnné prostředí.

Běžné příznaky a nejrychlejší kontrola

Závěrečná sebekontrola: ověřte konfiguraci ve správném pořadí

Před prohlášením, že je problém vyřešen, projděte tento kontrolní seznam:

1. Potvrďte, že Project URL Supabase pochází z projektu, který skutečně zamýšlíte použít.
2. Pro kód klienta/prohlížeče potvrďte, že používáte aktuální publishable klíč nebo stále aktivní starší klíč anon – nikoli tajný klíč.
3. Potvrďte, že kód a soubor prostředí používají stejné názvy proměnných.
4. Pro klientský kód Next.js použijte NEXT_PUBLIC_* a přímé odkazy process.env.NÁZEV_PROMĚNNÉ.
5. Pro klientský kód Vite použijte VITE_* a import.meta.env.NÁZEV_PROMĚNNÉ.
6. Ponechte .env.local v kořeni aplikace, nikoli uvnitř /src.
7. Po úpravě souborů prostředí restartujte vývojový server.
8. Pro produkci nastavte hodnoty ve správném prostředí nasazení a znovu sestavte/nasaďte.
9. Nelogujte ani nevystavujte klíče sb_secret_....
10. Odstraňte dočasné ladicí logy, jakmile je konfigurace potvrzena.

Když se createClient() inicializuje bez chyby chybějícího klíče, problém s proměnnými prostředí je vyřešen. Pokud následující požadavek na Supabase vrátí chybu autorizace, zabezpečení na úrovni řádků nebo oprávnění k tabulce, považujte to za samostatný problém. Platný API klíč nezaručuje, že volající smí číst nebo upravovat každý řádek; Supabase záměrně odděluje identifikaci API klíče od autentizace uživatele a autorizace databáze.

Trvalá oprava není „přejmenovávat klíč, dokud to nefunguje“. Je to sladění čtyř věcí: aktuálního typu klíče Supabase, názvu proměnné prostředí, pravidel vystavení frameworku a prostředí, ve kterém je aplikace skutečně sestavována nebo spouštěna. Jakmile si tyto věci rozumí, klient Supabase obdrží skutečný klíč místo undefined a matoucí konfigurační smyčka skončí.