makeplane/plane · critical · CommandError

{item} env variable is required.

Error message

{item} env variable is required.

What it means

CommandError raised by the `configure_instance` management command when the `SECRET_KEY` environment variable is unset/empty. `mandatory_keys = ["SECRET_KEY"]` and the loop checks `os.environ.get(item)` for a truthy value before seeding InstanceConfiguration rows. SECRET_KEY is the only hard-blocked key; all other instance config vars fall back to defaults.

Source

Thrown at apps/api/plane/license/management/commands/configure_instance.py:26

# Django imports
from django.core.management.base import BaseCommand, CommandError

# Module imports
from plane.license.models import InstanceConfiguration
from plane.utils.instance_config_variables import instance_config_variables


class Command(BaseCommand):
    help = "Configure instance variables"

    def handle(self, *args, **options):
        from plane.license.utils.encryption import encrypt_data

        mandatory_keys = ["SECRET_KEY"]

        for item in mandatory_keys:
            if not os.environ.get(item):
                raise CommandError(f"{item} env variable is required.")

        for item in instance_config_variables:
            obj, created = InstanceConfiguration.objects.get_or_create(key=item.get("key"))
            if created:
                obj.category = item.get("category")
                obj.is_encrypted = item.get("is_encrypted", False)
                if item.get("is_encrypted", False):
                    obj.value = encrypt_data(item.get("value"))
                else:
                    obj.value = item.get("value")
                obj.save()
                self.stdout.write(self.style.SUCCESS(f"{obj.key} loaded with value from environment variable."))
            else:
                self.stdout.write(self.style.WARNING(f"{obj.key} configuration already exists"))

View on GitHub (pinned to 1c8a60f858)

Solutions

1. Generate and export a SECRET_KEY before running the command: `export SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(50))")`.
2. Ensure your `.env` (or docker-compose env_file) has a non-empty SECRET_KEY and that the process actually sources it.
3. Re-run `python manage.py configure_instance` once SECRET_KEY is set.
4. Verify with `echo ${SECRET_KEY:?unset}` that the var is non-empty in the exact shell running the command.

Example fix

# before - .env
SECRET_KEY=

# after
SECRET_KEY=replace-with-50+-char-random-string

import os

def has_mandatory_env() -> bool:
    # mirrors configure_instance.py:25 mandatory_keys
    return all(os.environ.get(k) for k in ['SECRET_KEY'])

from django.core.management.base import CommandError
try:
    call_command('configure_instance')
except CommandError as e:
    if 'SECRET_KEY' in str(e):
        generate_and_export_secret_key()

When it happens

Trigger: Running `python manage.py configure_instance` without `SECRET_KEY` exported in the environment. The command aborts before writing any InstanceConfiguration rows.

Common situations: Fresh self-hosted install where `.env` was copied from `.env.example` but SECRET_KEY left blank; running the command in a shell/CI job that did not source the env file; Docker container started without the SECRET_KEY env var passed through.

Related errors

• Machine signature is required
• User email is required and should have signed in plane
• Please provide the email of the admin.
• User with the provided email does not exist.
• The provided email is already an instance admin.

AI-assisted analysis of makeplane/plane@1c8a60f858 (2026-08-12). Data as JSON: /api/errors/79b287fd1f820b84. Report an issue: GitHub.