This is the single easiest thing to get wrong when setting up or moving a self-hosted shop. Read this before you enter any Stripe, email or AI keys.
What It Protects
Passwords and API keys that you save in your shop are never stored in plain text. They are locked in the database using a key that you generate yourself, your ENCRYPTION_KEY. Without the exact key that locked them, nothing can read them back, neither you nor the shop. The values protected are:
- Your Stripe secret key and Stripe webhook secret
- Your email (SMTP) password
- Your email marketing provider's API key
- Your AI provider's API key
- Your Pinterest conversion token
- Your Google and Microsoft login client secrets (Site Settings, Social Login)
Anything you keep only in your .env file is not locked with this key. The Claude connector (MCP) secret is not locked with it either, so changing the key does not affect the connector.
Generating It
With your virtual environment activated, run:
python manage.py generate_encryption_key
Add the value it prints to your .env file, replacing the placeholder text that is in .env.example:
ENCRYPTION_KEY=your-generated-key-here
Restart the shop after saving the file. Do this once, early, before you enter any Stripe, email or AI keys. Every key you save afterwards is locked with whichever encryption key is active at that moment.
What You See If It Is Missing
If you try to save a Stripe, email or AI key without an encryption key, the admin shows a red error saying the server has no ENCRYPTION_KEY, and nothing is saved. Fix it by generating a key as above, restarting, and entering the key again. Older versions of the shop failed silently here, which was hard to spot.
The Failure That Actually Happens
The quiet failure is a different key, or a key that has dropped out of the .env file. If you move to a new server, restore a database backup, upload a .env from a different copy, or start a fresh .env from .env.example without carrying over the same ENCRYPTION_KEY, the shop cannot unlock the keys already saved in your database. They read back as blank. Anything that depends on a key you saved in the admin, such as Stripe, email, your email list or Google login, can stop working with no obvious error.
This catches people who follow the local-first route. You build and test your shop on your own computer, then upload the database to your server. That database holds your keys locked with your local encryption key, so the server's .env must carry the same ENCRYPTION_KEY. Other settings, such as SECRET_KEY, can be new for production. The encryption key must not.
What to Look For If the Key Is Missing or Has Changed
Nothing crashes, so you have to know the signs. Check for these:
- The Sign in with Google or Microsoft button has gone from your login page. The shop cannot read the saved client secret, so it stops offering that sign-in. In Site Settings, Social Login, the Client ID is still there but the secret box is empty.
- A red error about ENCRYPTION_KEY when you try to save a Stripe, email, AI or login secret in the admin.
- Your server log shows a warning. "Cannot decrypt: ENCRYPTION_KEY not configured" means the key is missing from .env. "Decryption failed: Invalid token (wrong key or corrupted data)" means a key is there but it is not the one that locked your saved values.
- Stripe may look fine when it is not. If your Stripe keys are also in .env, the shop quietly uses those when it cannot read the saved ones. Working payments do not prove the key is right.
- AI features say no key is set, or sign-ups stop reaching your email provider.
To check quickly, open your .env file on the server and confirm there is exactly one line starting ENCRYPTION_KEY= with a value after it, and that it is the same value you saved in your password manager.
If You Have Lost the Key
- Look for the original first. Check your password manager, the .env on your own computer, and any older copy of .env you kept. If you find it, put that line back in the server's .env and restart the shop. Everything saved becomes readable again.
- If it is gone for good, generate a new one with python manage.py generate_encryption_key. Add it on its own line in the server's .env and in your local .env, then restart the shop. A restart is needed, because the shop only reads .env when it starts.
- Enter your secrets again. The old values cannot be converted to the new key. In the admin, re-enter your Stripe secret key and webhook secret, email password, email marketing and AI keys, Pinterest token, and your Google and Microsoft client secrets, whichever you use.
- Check each one. Reload your login page to see the Google or Microsoft button, send a test email, and make a Stripe test purchase.
- Save the new key in your password manager straight away.
How to Avoid It
- Back up your ENCRYPTION_KEY alongside your database. A database backup without the matching key is only half a backup. Your .env file is not included in the admin backup, so copy it somewhere safe yourself.
- Keep the same key in your local .env and your server .env. Before you upload or replace a live .env, check the ENCRYPTION_KEY line is still in it and matches your saved copy.
- When moving to a new server or uploading a build, copy your existing .env across, or at minimum the exact ENCRYPTION_KEY line. Never generate a new one on a shop that already has keys saved.
- Only run generate_encryption_key once, on a brand-new install. If you ever lose the key, nothing else is damaged. You generate a new one and enter your saved keys again, because old values cannot be converted to a new key.
If Stripe, email or Google login stops working after a redeploy or server move with no obvious cause, check this first: is the ENCRYPTION_KEY in the current .env the same value as before the move?