Slik fikser du Django-feilen “ImproperlyConfigured: The SECRET_KEY Setting Must Not Be Empty”

Hvis Django gir feilmeldingen django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty, er det umiddelbare problemet enkelt: innstillingsmodulen Django lastet, gir ikke en brukbar SECRET_KEY-verdi ved kjøretid. Fiks verdien i innstillingsmodulen som faktisk brukes, eller sørg for at miljøvariabelen som leverer den, når Django-prosessen. Ikke løs et produksjonsproblem ved å commite en permanent hemmelighet til kildekoden.

Denne veiledningen er kontrollert mot Django 6.1-dokumentasjonen. Django 6.1 ble utgitt 5. august 2026. Kjerneregelen er eksplisitt: SECRET_KEY har tom streng som standardverdi, må være unik og uforutsigbar, og Django nekter å starte når den ikke er satt. Se den offisielle Django SECRET_KEY-innstillingsreferansen.

Hva betyr egentlig “SECRET_KEY setting must not be empty”?

Det betyr at da Django prøvde å bruke settings.SECRET_KEY, var den løste verdien tom eller på annen måte manglende. I et nylig opprettet prosjekt skriver django-admin startproject normalt en generert nøkkel inn i settings.py. Feilen er derfor spesielt vanlig etter at et prosjekt har blitt omorganisert for flere miljøer, flyttet til miljøvariabler, distribuert til en ny tjeneste, eller startet med en annen innstillingsmodul.

Det første nyttige spørsmålet er ikke “Hvordan finner jeg på en vilkårlig streng som får serveren til å starte?” Det er “Hvor skal denne distribusjonen hente sin hemmelighet fra?” Denne distinksjonen er viktig fordi en eksisterende produksjonsapplikasjon normalt bør gjenopprette sin tiltenkte hemmelighet i stedet for å stille generere en annen ved hver oppstart.

Vanlige kode mønstre som produserer feilen

SECRET_KEY = ""

# Manglende miljøvariabel returnerer None
SECRET_KEY = os.getenv("SECRET_KEY")

# Manglende miljøvariabel faller stille tilbake til en tom streng
SECRET_KEY = os.getenv("SECRET_KEY", "")

Alle tre etterlater Django uten en brukbar hemmelighet når den eksterne verdien er fraværende. For en produksjonskonfigurasjon demonstrerer Djangos egen distribusjonssjekkliste en fail-fast-form:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

Med dette mønsteret vil en manglende prosessmiljøvariabel feile umiddelbart i stedet for stille å bli en tom verdi. Den offisielle Django-distribusjonssjekklisten sier også at produksjonsnøkkelen bør være en stor tilfeldig verdi, holdes hemmelig, ikke gjenbrukes andre steder, og ikke commites til kildekoden.

Hvilken innstillingsfil laster Django faktisk?

Før du redigerer en fil, bekreft at det er filen kommandoen eller applikasjonsserveren din bruker. Django velger en innstillingsmodul via DJANGO_SETTINGS_MODULE, en Python-sti som mysite.settings eller config.settings.production. Den offisielle Django-innstillingsveiledningen dokumenterer denne mekanismen og --settings-kommandolinjealternativet.

For eksempel vil endring av config/settings.py ikke hjelpe hvis tjenesten starter Django med:

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

På samme måte kan et produksjons-WSGI- eller ASGI-inngangspunkt angi en annen modul. Inspekter manage.py, wsgi.py, asgi.py, og den faktiske serverkommandoen eller tjenestekonfigurasjonen. Hvis du bevisst bruker en produksjonsinnstillingsmodul, test den samme modulen eksplisitt i stedet for å teste en utviklingsfil og anta at resultatet overføres.

Bør du generere en ny SECRET_KEY eller gjenopprette den gamle?

For et helt nytt lokalt prosjekt: å generere en ny sikker verdi er rimelig. Pythons standard secrets-modul er designet for kryptografisk sterk tilfeldighet. En portabel kommando er:

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

Python-dokumentasjonen beskriver secrets som modulen for å generere sikre tilfeldige verdier egnet for passord, autentiseringstokens og relaterte hemmeligheter. Se den offisielle Python secrets-dokumentasjonen.

For en eksisterende produksjonsapplikasjon som pleide å fungere: prøv først å gjenopprette den samme tiltenkte hemmeligheten fra hemmelighetslageret eller distribusjonskonfigurasjonen. Django bruker SECRET_KEY for kryptografisk signering og for flere funksjoner, inkludert visse sesjons- og meldingskonfigurasjoner og passordtilbakestillingstokens. Å erstatte nøkkelen uventet kan ugyldiggjøre signerte data. Hvis den gamle nøkkelen ikke var kompromittert og feilen bare er en miljøinjeksjonsfeil, vil gjenoppretting vanligvis unngå en unødvendig rotasjon.

Hvis den gamle nøkkelen var eksponert: roter den. Django 6.1 støtter SECRET_KEY_FALLBACKS for planlagt rotasjon, noe som lar gamle nøkler aksepteres midlertidig mens ny signering bruker den nye nøkkelen. Fjern fallback-nøkler når overgangsperioden er over. Atferden og avveiningen er dokumentert i den offisielle SECRET_KEY_FALLBACKS-referansen.

Hva er den raskeste sikre fiksen for lokal utvikling?

Hvis du bare prøver å få opp et engangslokalt prosjekt, kan du sette en generert kun-for-utvikling-verdi i den aktive innstillingsfilen lenge nok til å bekrefte diagnosen:

SECRET_KEY = "replace-this-with-a-random-development-only-value"

Start så Django på nytt. Hvis feilen forsvinner, har du bekreftet at den tomme innstillingen var blokkeringen. Ikke kopier en produksjonshemmelighet til en utvikler-laptop bare for å gjøre lokal oppsett praktisk, og behandle ikke en hardkodet utviklingsverdi som din produksjonsdesign.

Når miljøvariabelen virkelig Django-prosessen?

Dette er den viktigste sjekken når innstillingsfilen allerede inneholder SECRET_KEY = os.environ["SECRET_KEY"] eller en tilsvarende oppslag. Variabelen må eksistere i miljøet til den nøyaktige prosessen som importerer Django-innstillinger. Å sette den i én terminal plasserer den ikke automatisk inne i en allerede kjørende tjeneste, container, prosessbehandler, CI-jobb eller separat shell.

Test tilstedeværelse uten å skrive ut selve hemmeligheten:

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

Hvis dette skriver ut False, fiks miljøinjeksjonen for den prosessen. For en rask lokal shell-test, bruk syntaksen for din shell og start så Django fra samme shell. For eksempel:

# macOS / Linux shell
export SECRET_KEY='your-generated-local-secret'
python manage.py runserver

# Windows PowerShell
$env:SECRET_KEY = 'your-generated-local-secret'
python manage.py runserver

For produksjon, bruk hemmelighets-/konfigurasjonsmekanismen levert av hostingplattformen eller prosessbehandleren i stedet for å plassere verdien i en kommando som kan bli lagret i shell-historikken.

Hvorfor løste ikke å legge SECRET_KEY til en .env-fil Django?

En .env-fil er bare en fil til noe laster innholdet inn i prosessmiljøet eller innstillingskoden din leser den. Djangos offisielle eksempel leser os.environ; Django krever eller dokumenterer ikke et innebygd automatisk .env-lastetrinn. Hvis prosjektet ditt er avhengig av et dotenv-bibliotek, rammeverkwrapper, containerkonfigurasjon eller distribusjonsplattform for å laste den filen, verifiser den komponenten separat og verifiser at den kjører før settings.py leser SECRET_KEY.

En nyttig handling er å kjøre den boolske miljøsjekken ovenfor fra samme container, tjenestekonto, shell eller utførelsesstadium som feiler. Hvis den skriver ut False, vil feilsøking av innholdet i settings.py alene ikke fikse prosessnivåkonfigurasjonsproblemet.

Hva om feilen bare vises i Docker, CI, collectstatic, WSGI eller ASGI?

Det betyr vanligvis at en annen prosess eller utførelsesstadium laster prosjektet med et annet miljø eller innstillingsmodul. Feilen kan dukke opp under collectstatic, migreringer, tester, en CI-sjekk, oppstart av applikasjonsserver eller en bakgrunnsprosess selv om runserver fungerer på laptopen din.

Ikke anta at en hemmelighet tilgjengelig ved kjøretid også er tilgjengelig under et bildebygge- eller CI-trinn. Omvendt, ikke anta at en variabel eksportert i et interaktivt shell er synlig for en systemtjeneste. Sjekk disse to faktaene i den feilende konteksten:

• Hvilken DJANGO_SETTINGS_MODULE eller --settings-verdi brukes?
• Har den nøyaktige prosessen en ikke-tom SECRET_KEY-miljøvariabel før Django importerer innstillinger?

Den spesifikke måten å injisere en hemmelighet på avhenger av Docker, CI-leverandøren, verten eller prosessbehandleren. Bruk den plattformens offisielle hemmelighetsbehandlingsmekanisme. Django-sidens krav forblir det samme: den valgte innstillingskonfigurasjonen må levere en ikke-tom hemmelighet ved kjøretid.

Hvordan verifiserer du fiksen uten å eksponere nøkkelen?

Først, ikke skriv ut den faktiske produksjonsnøkkelen til logger bare for å bevise at den eksisterer. Verifiser tilstedeværelse med en boolsk sjekk, la så Django laste konfigurasjonen:

python manage.py check

For en produksjonskonfigurasjon anbefaler Django å kjøre distribusjonssjekker mot produksjonsinnstillingsfilen:

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

Erstatt modulstien med din virkelige produksjonsinnstillingsmodul. Den offisielle distribusjonssjekklisten anbefaler spesifikt check --deploy og advarer om at den bør kjøres mot produksjonsinnstillinger.

Til slutt, start den faktiske applikasjonsprosessen på nytt. En variabel lagt til etter at en tjeneste startet, vil vanligvis ikke påvirke den allerede kjørende prosessen. Hvis den omstartede prosessen består Djangos sjekker og ikke lenger gir unntaket, er konfigurasjonsproblemet løst.

Hvilke fiks bør du unngå?

• Ikke sett SECRET_KEY = "" eller bruk en tom standardverdi. Det reproduserer tilstanden Django avviser.
• Ikke generer en ny nøkkel ved hver applikasjonsoppstart. En endrende nøkkel kan ugyldiggjøre signerte data og skape inkonsekvent atferd på tvers av flere arbeidere.
• Ikke kopier en hemmelighet fra en veiledning eller et annet prosjekt. Django krever en unik, uforutsigbar verdi, og en offentlig verdi ødelegger hensikten med en hemmelighet.
• Ikke commit produksjonsnøkkelen til Git. Djangos distribusjonssjekkliste anbefaler uttrykkelig å holde den utenfor kildekoden.
• Ikke skriv ut hele nøkkelen til CI- eller produksjonslogger. Sjekk bare om den er til stede med mindre du har en kontrollert hemmelighetsrevisjonsprosedyre.
• Ikke anta at en .env-fil er lastet bare fordi den eksisterer. Bekreft lastemekanismen og det faktiske prosessmiljøet.

En praktisk beslutningsvei

Endelig sjekkliste

• Bekreft den nøyaktige innstillingsmodulen Django laster.
• Bekreft at SECRET_KEY løses til en ikke-tom verdi i det miljøet.
• Bruk en unik, uforutsigbar verdi; ikke gjenbruk en offentlig eller veiledningsnøkkel.
• Hold produksjonsnøkkelen utenfor kildekoden.
• Hvis du bruker miljøvariabler, sørg for at variabelen når hver prosess som importerer Django-innstillinger.
• Hvis du bruker en .env-arbeidsflyt, verifiser lasteren i stedet for å anta at Django leser filen automatisk.
• Gjenopprett den gamle produksjonsnøkkelen hvis problemet er utilsiktet konfigurasjonstap; roter kun når det er tiltenkt eller nødvendig.
• Kjør python manage.py check, og for produksjon kjør check --deploy mot produksjonsinnstillingsmodulen.
• Start den faktiske tjenesten på nytt etter å ha endret miljøet.

Hovedpoenget er at dette unntaket ikke ber om en bestemt magisk streng. Det forteller deg at Djangos aktive innstillinger ikke inneholder en brukbar hemmelighet. Fiks kilden til den konfigurasjonen, bevar den tiltenkte produksjonsnøkkelen der det er hensiktsmessig, og verifiser resultatet i samme prosessmiljø som opprinnelig feilet.