Kako riješiti Django grešku “ImproperlyConfigured: The SECRET_KEY Setting Must Not Be Empty”

Ako Django prijavi grešku django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty, neposredni problem je jednostavan: modul postavki koji je Django učitao ne pruža upotrebljivu vrijednost SECRET_KEY tijekom izvršavanja. Ispravite vrijednost u modulu postavki koji se stvarno koristi ili provjerite dolazi li varijabla okruženja koja je osigurava do Django procesa. Ne rješavajte problem na produkciji tako da trajni tajni ključ commitate u sustav za kontrolu verzija.

Ovaj vodič provjeren je u odnosu na dokumentaciju Django verzije 6.1. Django 6.1 objavljen je 5. kolovoza 2026. Osnovno pravilo je eksplicitno: SECRET_KEY zadano ima prazan niz, mora biti jedinstven i nepredvidiv, a Django odbija pokretanje ako nije postavljen. Pogledajte službenu referencu za Django SECRET_KEY postavku.

Što zapravo znači “SECRET_KEY setting must not be empty”?

To znači da je kada je Django pokušao koristiti settings.SECRET_KEY, riješena vrijednost bila prazna ili na neki drugi način nedostajala. U novostvorenom projektu, django-admin startproject obično upisuje generirani ključ u settings.py. Stoga je ova greška posebno česta nakon što je projekt reorganiziran za više okruženja, premješten na varijable okruženja, implementiran na novu uslugu ili pokrenut s drugačijim modulom postavki.

Prvo korisno pitanje nije “Kako da izmislim bilo koji niz koji će pokrenuti poslužitelj?” Već je “Gdje ovo implementirano okruženje treba dobiti svoj tajni ključ?” Ta razlika je važna jer bi postojeća aplikacija u produkciji obično trebala povratiti namijenjeni tajni ključ, umjesto da tiho generira drugačiji pri svakom pokretanju.

Uobičajeni obrasci koda koji uzrokuju grešku

SECRET_KEY = ""

# Nedostajuća varijabla okruženja vraća None
SECRET_KEY = os.getenv("SECRET_KEY")

# Nedostajuća varijabla okruženja tiho pada na prazan niz
SECRET_KEY = os.getenv("SECRET_KEY", "")

Sva tri slučaja ostavljaju Django bez upotrebljivog tajnog ključa kada vanjska vrijednost nedostaje. Za konfiguraciju u produkciji, Django vlastiti popis za provjeru implementacije demonstrira obrazac koji brzo javlja grešku:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

Uz ovaj obrazac, nedostajuća varijabla okruženja procesa odmah uzrokuje grešku, umjesto da tiho postane prazna vrijednost. Službeni Django popis za provjeru implementacije također navodi da proizvodni ključ treba biti velika nasumična vrijednost, čuvana u tajnosti, ne smije se ponovno koristiti na drugim mjestima i ne smije se commitati u sustav za kontrolu verzija.

Koju datoteku postavki Django zapravo učitava?

Prije uređivanja datoteke, potvrdite da je to datoteka koju koristi vaša naredba ili aplikacijski poslužitelj. Django bira modul postavki putem DJANGO_SETTINGS_MODULE, Python putanje poput mysite.settings ili config.settings.production. Službeni Django vodič za postavke dokumentira ovaj mehanizam i opciju naredbenog retka --settings.

Na primjer, promjena config/settings.py neće pomoći ako usluga pokreće Django s:

python manage.py runserver --settings=config.settings.local

Slično tome, proizvodna WSGI ili ASGI ulazna točka može postaviti drugačiji modul. Pregledajte manage.py, wsgi.py, asgi.py i stvarnu naredbu poslužitelja ili konfiguraciju usluge. Ako namjerno koristite proizvodni modul postavki, eksplicitno testirajte taj isti modul umjesto da testirate razvojnu datoteku i pretpostavljate da se rezultat prenosi.

Trebate li generirati novi SECRET_KEY ili vratiti stari?

Za potpuno novi lokalni projekt: generiranje nove sigurne vrijednosti je razumno. Pythonov standardni modul secrets dizajniran je za kriptografski snažnu nasumičnost. Jedna prenosiva naredba je:

python -c "import secrets; print(secrets.token_urlsafe(64))"

Python dokumentacija opisuje secrets kao modul za generiranje sigurnih nasumičnih vrijednosti prikladnih za lozinke, autentifikacijske tokene i srodne tajne. Pogledajte službenu Python secrets dokumentaciju.

Za postojeću aplikaciju u produkciji koja je prije radila: prvo pokušajte vratiti istu namijenjenu tajnu iz vaše pohrane tajni ili konfiguracije implementacije. Django koristi SECRET_KEY za kriptografsko potpisivanje i za nekoliko značajki, uključujući određene konfiguracije sesija i poruka te tokene za poništavanje lozinke. Neočekivano zamjenjivanje ključa može poništiti potpisane podatke. Ako stari ključ nije bio kompromitiran i prekid je samo greška u ubacivanju okruženja, vraćanje obično izbjegava nepotrebnu rotaciju.

Ako je stari ključ bio izložen: rotirajte ga. Django 6.1 podržava SECRET_KEY_FALLBACKS za planiranu rotaciju, omogućujući da se stari ključevi privremeno prihvaćaju dok novo potpisivanje koristi novi ključ. Uklonite rezervne ključeve kada njihovo prijelazno razdoblje završi. Ponašanje i kompromisi dokumentirani su u službenoj SECRET_KEY_FALLBACKS referenci.

Koje je najbrže sigurno rješenje za lokalni razvoj?

Ako pokušavate samo pokrenuti jednokratni lokalni projekt, možete staviti generiranu vrijednost samo za razvoj u aktivnu datoteku postavki dovoljno dugo da potvrdite dijagnozu:

SECRET_KEY = "zamijeni-ovo-s-nasumicnom-vrijednoscu-samo-za-razvoj"

Zatim ponovno pokrenite Django. Ako greška nestane, potvrdili ste da je prazna postavka bila blokada. Ne kopirajte proizvodni tajni ključ na developerski laptop samo da bi lokalno postavljanje bilo prikladno i ne tretirajte hardkodiranu razvojnu vrijednost kao vaš proizvodni dizajn.

Dolazi li varijabla okruženja stvarno do Django procesa?

Ovo je najvažnija provjera kada vaša datoteka postavki već sadrži SECRET_KEY = os.environ["SECRET_KEY"] ili ekvivalentno pretraživanje. Varijabla mora postojati u okruženju točnog procesa koji uvozi Django postavke. Postavljanje u jednom terminalu ne stavlja je automatski unutar već pokrenute usluge, spremnika, upravitelja procesa, CI posla ili zasebne ljuske.

Testirajte prisutnost bez ispisivanja same tajne:

python -c "import os; print(bool(os.environ.get('SECRET_KEY')))"

Ako ovo ispiše False, popravite ubacivanje okruženja za taj proces. Za brzi lokalni test ljuske, koristite sintaksu za svoju ljusku i zatim pokrenite Django iz iste ljuske. Na primjer:

# macOS / Linux ljuska
export SECRET_KEY='vasa-generirana-lokalna-tajna'
python manage.py runserver

# Windows PowerShell
$env:SECRET_KEY = 'vasa-generirana-lokalna-tajna'
python manage.py runserver

Za produkciju koristite mehanizam tajni/konfiguracije koji pruža vaša hosting platforma ili upravitelj procesa, umjesto da vrijednost stavite u naredbu koja bi mogla biti spremljena u povijesti ljuske.

Zašto dodavanje SECRET_KEY u .env datoteku nije popravilo Django?

.env datoteka je samo datoteka dok nešto ne učita njezin sadržaj u okruženje procesa ili vaš kod postavki ne pročita je. Django službeni primjer čita os.environ; Django ne zahtijeva niti dokumentira ugrađeni automatski korak učitavanja .env. Ako vaš projekt oslanja na dotenv biblioteku, omotač okvira, konfiguraciju spremnika ili platformu za implementaciju da učitaju tu datoteku, zasebno provjerite tu komponentu i provjerite radi li prije nego što settings.py pročita SECRET_KEY.

Korisna radnja je pokretanje gore navedene boolean provjere okruženja iz istog spremnika, računa usluge, ljuske ili faze izvršavanja koja ne uspijeva. Ako ispiše False, otklanjanje grešaka u sadržaju settings.py samo po sebi neće popraviti problem konfiguracije na razini procesa.

Što ako se greška pojavljuje samo u Dockeru, CI-u, collectstatic, WSGI ili ASGI?

To obično znači da drugačiji proces ili faza izvršavanja učitava projekt s drugačijim okruženjem ili modulom postavki. Greška se može pojaviti tijekom collectstatic, migracija, testova, CI provjere, pokretanja aplikacijskog poslužitelja ili pozadinskog procesa, iako runserver radi na vašem laptopu.

Ne pretpostavljajte da je tajna dostupna tijekom izvršavanja također dostupna tijekom izgradnje slike ili CI koraka. Obrnuto, ne pretpostavljajte da je varijabla izvezena u interaktivnoj ljusci vidljiva sustavnoj usluzi. Provjerite ove dvije činjenice u kontekstu koji ne uspijeva:

• Koja se DJANGO_SETTINGS_MODULE ili --settings vrijednost koristi?
• Ima li taj točan proces nepraznu SECRET_KEY varijablu okruženja prije nego što Django uveze postavke?

Specifičan način ubacivanja tajne ovisi o Dockeru, vašem CI pružatelju, vašem hostu ili vašem upravitelju procesa. Koristite službeni mehanizam za upravljanje tajnima te platforme. Zahtjev na Django strani ostaje isti: odabrana konfiguracija postavki mora pružiti nepraznu tajnu tijekom izvršavanja.

Kako provjeriti popravak bez izlaganja ključa?

Prvo, nemojte ispisivati stvarni proizvodni ključ u zapise samo da biste dokazali da postoji. Potvrdite prisutnost boolean provjerom, a zatim dopustite Djangou da učita konfiguraciju:

python manage.py check

Za proizvodnu konfiguraciju, Django preporučuje pokretanje provjera implementacije protiv proizvodne datoteke postavki:

python manage.py check --deploy --settings=config.settings.production

Zamijenite putanju modula stvarnim proizvodnim modulom postavki. Službeni popis za provjeru implementacije specifično preporučuje check --deploy i upozorava da ga treba pokrenuti protiv proizvodnih postavki.

Naposljetku, ponovno pokrenite stvarni proces aplikacije. Varijabla dodana nakon što je usluga pokrenuta obično neće utjecati na taj već pokrenuti proces. Ako ponovno pokrenuti proces prođe Django provjere i više ne baca iznimku, problem konfiguracije je riješen.

Koje popravke trebate izbjegavati?

• Nemojte postavljati SECRET_KEY = "" ili koristiti praznu zadanu vrijednost. To reproducira uvjet koji Django odbija.
• Nemojte generirati novi ključ pri svakom pokretanju aplikacije. Ključ koji se mijenja može poništiti potpisane podatke i stvoriti nekonzistentno ponašanje između više radnika.
• Nemojte kopirati tajnu iz tutorijala ili drugog projekta. Django zahtijeva jedinstvenu, nepredvidivu vrijednost, a javna vrijednost poništava svrhu tajne.
• Nemojte commitati proizvodni ključ u Git. Django popis za provjeru implementacije izričito savjetuje da ga držite izvan sustava za kontrolu verzija.
• Nemojte ispisivati cijeli ključ u CI ili proizvodne zapise. Provjerite samo postoji li, osim ako nemate kontrolirani postupak revizije tajni.
• Nemojte pretpostavljati da je .env datoteka učitana samo zato što postoji. Potvrdite mehanizam učitavanja i stvarno okruženje procesa.

Praktičan put odluke

Konačni popis za provjeru

• Potvrdite točan modul postavki koji Django učitava.
• Potvrdite da se SECRET_KEY rješava na nepraznu vrijednost u tom okruženju.
• Koristite jedinstvenu, nepredvidivu vrijednost; nemojte ponovno koristiti javni ili tutorijalni ključ.
• Držite proizvodni ključ izvan sustava za kontrolu verzija.
• Ako koristite varijable okruženja, pobrinite se da varijabla dođe do svakog procesa koji uvozi Django postavke.
• Ako koristite .env tijek rada, provjerite učitavač umjesto da pretpostavljate da Django automatski čita datoteku.
• Vratite stari proizvodni ključ ako je problem slučajni gubitak konfiguracije; rotirajte samo kada je namijenjeno ili zahtijevano.
• Pokrenite python manage.py check, a za produkciju pokrenite check --deploy protiv modula proizvodnih postavki.
• Ponovno pokrenite stvarnu uslugu nakon promjene njezinog okruženja.

Ključna točka je da ova iznimka ne traži određenu čarobnu nisku. Ona vam govori da Django aktivne postavke ne sadrže upotrebljivu tajnu. Popravite izvor te konfiguracije, sačuvajte namijenjeni proizvodni ključ kada je prikladno i provjerite rezultat u istom okruženju procesa koje je izvorno ne uspjelo.