Sådan løser du Django-fejlen “ImproperlyConfigured: The SECRET_KEY Setting Must Not Be Empty”

Hvis Django udløser django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty, er det umiddelbare problem simpelt: Det indstillingsmodul, Django har indlæst, stiller ikke en brugbar SECRET_KEY-værdi til rådighed ved kørselstid. Ret værdien i det indstillingsmodul, der faktisk bliver brugt, eller sørg for, at miljøvariablen, der leverer den, når frem til Django-processen. Løs ikke et produktionsproblem ved at committe en permanent hemmelighed til kildekontrol.

Denne guide er verificeret mod Django 6.1-dokumentationen. Django 6.1 blev udgivet den 5. august 2026. Den grundlæggende regel er eksplicit: SECRET_KEY har som standard en tom streng, skal være unik og uforudsigelig, og Django nægter at starte, når den ikke er sat. Se den officielle Django SECRET_KEY-indstillingsreference.

Hvad betyder “SECRET_KEY setting must not be empty” egentlig?

Det betyder, at da Django forsøgte at bruge settings.SECRET_KEY, var den løste værdi tom eller på anden måde manglende. I et nyoprettet projekt skriver django-admin startproject normalt en genereret nøgle ind i settings.py. Fejlen er derfor særlig almindelig, efter at et projekt er blevet omorganiseret til flere miljøer, flyttet til miljøvariabler, udrullet til en ny tjeneste eller startet med et andet indstillingsmodul.

Det første nyttige spørgsmål er ikke “Hvordan finder jeg på en vilkårlig streng, der får serveren til at starte?” Det er “Hvor skal denne udrulning hente sin hemmelighed fra?” Denne distinktion er vigtig, fordi en eksisterende produktionsapplikation normalt skal gendanne sin tilsigtede hemmelighed frem for stille og roligt at generere en anden ved hver opstart.

Almindelige kode-mønstre, der producerer fejlen

SECRET_KEY = ""

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

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

Alle tre efterlader Django uden en brugbar hemmelighed, når den eksterne værdi er fraværende. For en produktionskonfiguration demonstrerer Djangos egen udrulningscheckliste en fail-fast-form:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

Med dette mønster fejler en manglende procesmiljøvariabel øjeblikkeligt i stedet for stille at blive til en tom værdi. Den officielle Django-udrulningscheckliste angiver også, at produktionsnøglen skal være en stor tilfældig værdi, holdes hemmelig, ikke genbruges andre steder og ikke committes til kildekontrol.

Hvilken indstillingsfil indlæser Django faktisk?

Bekræft, før du redigerer en fil, at det er den fil, din kommando eller applikationsserver bruger. Django vælger et indstillingsmodul via DJANGO_SETTINGS_MODULE, en Python-sti som mysite.settings eller config.settings.production. Den officielle Django-indstillingsguide dokumenterer denne mekanisme og --settings-kommandolinjevalget.

For eksempel vil ændring af config/settings.py ikke hjælpe, hvis tjenesten starter Django med:

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

Ligeledes kan et produktions-WSGI- eller ASGI-entrypoint angive et andet modul. Inspektér manage.py, wsgi.py, asgi.py og den faktiske serverkommando eller tjenestekonfiguration. Hvis du med vilje bruger et produktionsindstillingsmodul, så test det samme modul eksplicit i stedet for at teste en udviklingsfil og antage, at resultatet overføres.

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

For et helt nyt lokalt projekt: Det er rimeligt at generere en ny sikker værdi. Pythons standard secrets-modul er designet til kryptografisk stærk tilfældighed. En portabel kommando er:

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

Python-dokumentationen beskriver secrets som modulet til generering af sikre tilfældige værdier, der er egnet til adgangskoder, autentificeringstokens og relaterede hemmeligheder. Se den officielle Python secrets-dokumentation.

For en eksisterende produktionsapplikation, der plejede at virke: Prøv først at gendanne den samme tilsigtede hemmelighed fra din hemmelighedsbutik eller udrulningskonfiguration. Django bruger SECRET_KEY til kryptografisk signering og til flere funktioner, inklusive visse session- og meddelelseskonfigurationer og tokens til nulstilling af adgangskoder. Uventet udskiftning af nøglen kan ugyldiggøre signeret data. Hvis den gamle nøgle ikke var kompromitteret, og nedbruddet blot er en fejl i miljøinjektionen, undgår gendannelse af den normalt en unødvendig rotation.

Hvis den gamle nøgle var eksponeret: Rotér den. Django 6.1 understøtter SECRET_KEY_FALLBACKS til planlagt rotation, hvilket tillader, at gamle nøgler accepteres midlertidigt, mens ny signering bruger den nye nøgle. Fjern fallback-nøgler, når deres overgangsperiode er overstået. Adfærden og afvejningen er dokumenteret i den officielle SECRET_KEY_FALLBACKS-reference.

Hvad er den hurtigste sikre løsning til lokal udvikling?

Hvis du kun forsøger at få et engangslokalt projekt op at køre, kan du sætte en genereret udviklingskun-værdi i den aktive indstillingsfil længe nok til at bekræfte diagnosen:

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

Start derefter Django igen. Hvis fejlen forsvinder, har du bekræftet, at den tomme indstilling var blokkeren. Kopier ikke en produktionshemmelighed til en udvikler-laptop blot for at gøre lokal opsætning bekvem, og behandl ikke en hårdkodet udviklingsværdi som dit produktionsdesign.

Når miljøvariablen virkelig frem til Django-processen?

Dette er den vigtigste kontrol, når din indstillingsfil allerede indeholder SECRET_KEY = os.environ["SECRET_KEY"] eller en ækvivalent opslag. Variablen skal eksistere i miljøet for den præcise proces, der importerer Django-indstillinger. At sætte den i én terminal placerer den ikke automatisk inde i en allerede kørende tjeneste, container, proceshåndtering, CI-job eller separat shell.

Test tilstedeværelse uden at udskrive selve hemmeligheden:

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

Hvis dette udskriver False, skal du rette miljøinjektionen for den proces. For en hurtig lokal shell-test skal du bruge syntaksen for din shell og derefter starte Django fra den 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 produktion skal du bruge den hemmeligheds-/konfigurationsmekanisme, der leveres af din hostingplatform eller proceshåndtering, frem for at placere værdien i en kommando, der måske gemmes i shell-historikken.

Hvorfor løste tilføjelsen af SECRET_KEY til en .env-fil ikke Django?

En .env-fil er bare en fil, indtil noget indlæser dens indhold i procesmiljøet, eller din indstillingskode læser den. Djangos officielle eksempel læser os.environ; Django kræver eller dokumenterer ikke et indbygget automatisk .env-indlæsningstrin. Hvis dit projekt er afhængigt af et dotenv-bibliotek, framework-wrapper, containerkonfiguration eller udrulningsplatform til at indlæse den fil, skal du verificere den komponent separat og verificere, at den kører, før settings.py læser SECRET_KEY.

En nyttig handling er at køre den ovenstående boolean miljøkontrol fra den samme container, tjenestekonto, shell eller eksekveringstrin, der fejler. Hvis den udskriver False, vil fejlfinding af indholdet af settings.py alene ikke løse procesniveau-konfigurationsproblemet.

Hvad hvis fejlen kun optræder i Docker, CI, collectstatic, WSGI eller ASGI?

Det betyder normalt, at en anden proces eller eksekveringstrin indlæser projektet med et andet miljø eller indstillingsmodul. Fejlen kan dukke op under collectstatic, migrationer, tests, et CI-tjek, opstart af applikationsserver eller en baggrundsproces, selvom runserver virker på din laptop.

Antag ikke, at en hemmelighed, der er tilgængelig ved kørselstid, også er tilgængelig under et image-build eller CI-trin. Omvendt skal du ikke antage, at en variabel, der er eksporteret i en interaktiv shell, er synlig for en systemtjeneste. Tjek disse to fakta i den fejlede kontekst:

• Hvilken DJANGO_SETTINGS_MODULE eller --settings-værdi bliver brugt?
• Har den præcise proces en ikke-tom SECRET_KEY-miljøvariabel, før Django importerer indstillinger?

Den specifikke måde at injicere en hemmelighed på afhænger af Docker, din CI-udbyder, din host eller din proceshåndtering. Brug den platforms officielle hemmelighedsstyringsmekanisme. Kravet på Django-siden forbliver det samme: Den valgte indstillingskonfiguration skal levere en ikke-tom hemmelighed ved kørselstid.

Hvordan verificerer du løsningen uden at eksponere nøglen?

Først, udskriv ikke den faktiske produktionsnøgle i logfiler blot for at bevise, at den eksisterer. Verificér tilstedeværelse med en boolean kontrol, og lad derefter Django indlæse konfigurationen:

python manage.py check

For en produktionskonfiguration anbefaler Django at køre udrulningstjek mod produktionsindstillingsfilen:

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

Erstat modulstien med dit rigtige produktionsindstillingsmodul. Den officielle udrulningscheckliste anbefaler specifikt check --deploy og advarer om, at den skal køres mod produktionsindstillinger.

Til sidst, genstart den faktiske applikationsproces. En variabel, der er tilføjet, efter at en tjeneste er startet, vil normalt ikke påvirke den allerede kørende proces. Hvis den genstartede proces består Djangos tjek og ikke længere udløser undtagelsen, er konfigurationsproblemet løst.

Hvilke løsninger bør du undgå?

• Indstil ikke SECRET_KEY = "" eller brug en tom standardværdi. Det reproducerer den betingelse, Django afviser.
• Generer ikke en ny nøgle ved hver applikationsopstart. En ændrende nøgle kan ugyldiggøre signeret data og skabe inkonsistent adfærd på tværs af flere arbejdere.
• Kopier ikke en hemmelighed fra en tutorial eller et andet projekt. Django kræver en unik, uforudsigelig værdi, og en offentlig værdi underminerer formålet med en hemmelighed.
• Committ ikke produktionsnøglen til Git. Djangos udrulningscheckliste råder eksplicit til at holde den ude af kildekontrol.
• Udskriv ikke den fulde nøgle i CI- eller produktionslogs. Tjek kun, om den er til stede, medmindre du har en kontrolleret hemmelighedsrevisionsprocedure.
• Antag ikke, at en .env-fil er indlæst blot fordi den eksisterer. Bekræft indlæsningsmekanismen og det faktiske procesmiljø.

En praktisk beslutningssti

Endelig tjekliste

• Bekræft det præcise indstillingsmodul, Django indlæser.
• Bekræft at SECRET_KEY løses til en ikke-tom værdi i det miljø.
• Brug en unik, uforudsigelig værdi; genbrug ikke en offentlig eller tutorial-nøgle.
• Hold produktionsnøglen ude af kildekontrol.
• Hvis du bruger miljøvariabler, skal du sikre, at variablen når frem til hver proces, der importerer Django-indstillinger.
• Hvis du bruger en .env-workflow, skal du verificere loaderen frem for at antage, at Django læser filen automatisk.
• Gendan den gamle produktionsnøgle, hvis problemet er utilsigtet konfigurationstab; rotér kun, når det er tilsigtet eller påkrævet.
• Kør python manage.py check, og for produktion skal du køre check --deploy mod produktionsindstillingsmodulet.
• Genstart den faktiske tjeneste efter ændring af dens miljø.

Det vigtigste punkt er, at denne undtagelse ikke beder om en bestemt magisk streng. Den fortæller dig, at Djangos aktive indstillinger ikke indeholder en brugbar hemmelighed. Ret kilden til den konfiguration, bevar den tilsigtede produktionsnøgle, når det er passende, og verificér resultatet i det samme procesmiljø, der oprindeligt fejlede.