makeplane/plane · error · CommandError

Machine signature is required

Error message

Machine signature is required

What it means

CommandError raised by `register_instance` when the `machine_signature` argument is falsy. Note a latent bug: `options.get("machine_signature", "machine-signature")` supplies a truthy default, so the `if not machine_signature` branch can only fire when an empty string is explicitly passed - argparse already makes the positional required, so this guard is largely defensive. The raised error blocks Instance creation.

Source

Thrown at apps/api/plane/license/management/commands/register_instance.py:65

            data = response.json()
            return data.get("tag_name", fallback_version)
        except Exception:
            self.stdout.write("Error checking for latest version")
            return fallback_version

    def handle(self, *args, **options):
        # Check if the instance is registered
        instance = Instance.objects.first()

        current_version = self.check_for_current_version()
        latest_version = self.check_for_latest_version(current_version)

        # If instance is None then register this instance
        if instance is None:
            machine_signature = options.get("machine_signature", "machine-signature")

            if not machine_signature:
                raise CommandError("Machine signature is required")

            instance = Instance.objects.create(
                instance_name="Plane Community Edition",
                instance_id=secrets.token_hex(12),
                current_version=current_version,
                latest_version=latest_version,
                last_checked_at=timezone.now(),
                is_test=os.environ.get("IS_TEST", "0") == "1",
                edition=InstanceEdition.PLANE_COMMUNITY.value,
            )

            self.stdout.write(self.style.SUCCESS("Instance registered"))
        else:
            self.stdout.write(self.style.SUCCESS("Instance already registered"))

            # Update the instance details
            instance.last_checked_at = timezone.now()
            instance.current_version = current_version

View on GitHub (pinned to 1c8a60f858)

Solutions

1. Pass a non-empty machine_signature positional: `python manage.py register_instance <unique-host-id>`.
2. In wrapper scripts, default to a stable unique value (hostname, MAC hash, or a generated UUID) rather than an empty string.
3. If invoking programmatically, ensure `options["machine_signature"]` is a non-empty string before calling `handle()`.
4. Consider fixing the misleading `options.get(..., "machine-signature")` default so the guard is meaningful, or remove it since argparse enforces presence.

Example fix

# before
python manage.py register_instance ""

# after
python manage.py register_instance "$(hostname)-$(sha256sum /etc/machine-id | cut -c1-16)"

def is_valid_signature(sig) -> bool:
    # register_instance requires a non-empty positional signature
    return isinstance(sig, str) and bool(sig.strip())

# wrapper scripts should default to a stable unique value, never ''

from django.core.management.base import CommandError
try:
    call_command('register_instance', signature)
except CommandError as e:
    if 'Machine signature' in str(e):
        signature = derive_machine_id(); call_command('register_instance', signature)

When it happens

Trigger: Running `python manage.py register_instance ""` (explicit empty string). A bare `python manage.py register_instance` fails earlier at argparse because machine_signature is a required positional argument; passing a real signature string registers the instance successfully.

Common situations: Automation/wrapper scripts that pass an empty machine_signature under some code path; misconfigured installers that derive the signature from an unset env var and pass `""`; calling the command programmatically with a populated options dict that has `machine_signature: None`.

Related errors

• {item} env variable 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/d0c12787d5dc914e. Report an issue: GitHub.