goharbor/harbor · error · Exception

Error: The protocol is https but attribute ssl_cert_key is n

Error message

Error: The protocol is https but attribute ssl_cert_key is not set

What it means

Thrown by validate() in make/photon/prepare/utils/configs.py when harbor.yml declares 'protocol: https' but the private key path is empty or still the placeholder '/your/certificate/path' (default_https_key_path). The TLS key is required alongside the certificate to terminate HTTPS in the nginx proxy; one without the other is a fatal configuration error.

Source

Thrown at make/photon/prepare/utils/configs.py:33

default_https_key_path = '/your/certificate/path'

REGISTRY_USER_NAME = 'harbor_registry_user'


def validate(conf: dict, **kwargs):
    # hostname validate
    if conf.get('hostname') == '127.0.0.1':
        raise Exception("127.0.0.1 can not be the hostname")
    if conf.get('hostname') == 'reg.mydomain.com':
        raise Exception("Please specify hostname")

    # protocol validate
    protocol = conf.get("protocol")
    if protocol == "https":
        if not conf.get("cert_path") or conf["cert_path"] == default_https_cert_path:
            raise Exception("Error: The protocol is https but attribute ssl_cert is not set")
        if not conf.get("cert_key_path") or conf['cert_key_path'] == default_https_key_path:
            raise Exception("Error: The protocol is https but attribute ssl_cert_key is not set")
    if protocol == "http":
        logging.warning("WARNING: HTTP protocol is insecure. Harbor will deprecate http protocol in the future. Please make sure to upgrade to https")

    # log endpoint validate
    if ('log_ep_host' in conf) and not conf['log_ep_host']:
        raise Exception('Error: must set log endpoint host to enable external host')
    if ('log_ep_port' in conf) and not conf['log_ep_port']:
        raise Exception('Error: must set log endpoint port to enable external host')
    if ('log_ep_protocol' in conf) and (conf['log_ep_protocol'] not in ['udp', 'tcp']):
        raise Exception("Protocol in external log endpoint must be one of 'udp' or 'tcp' ")

    # Storage validate
    valid_storage_drivers = ["filesystem", "azure", "gcs", "s3", "swift", "oss"]
    storage_provider_name = conf.get("storage_provider_name")
    if storage_provider_name not in valid_storage_drivers:
        raise Exception("Error: storage driver %s is not supported, only the following ones are supported: %s" % (
            storage_provider_name, ",".join(valid_storage_drivers)))

View on GitHub (pinned to 7b2fd08cc5)

Solutions

Set 'https.private_key:' to the absolute path of the matching PEM private key on the Docker host, e.g. /data/cert/harbor.example.com.key
Confirm the key matches the certificate: openssl x509 -noout -modulus -in server.crt | openssl md5 vs openssl rsa -noout -modulus -in server.key | openssl md5
Re-run ./install.sh

Example fix

# harbor.yml (before)
https:
  certificate: /data/cert/harbor.example.com.crt
  private_key: /your/certificate/path

# harbor.yml (after)
https:
  certificate: /data/cert/harbor.example.com.crt
  private_key: /data/cert/harbor.example.com.key

Defensive patterns

Strategy: validation

Validate before calling

PLACEHOLDER = '/your/certificate/path'
https_cfg = cfg.get('https') or {}
key = https_cfg.get('private_key', '')
if https_cfg and (not key or key == PLACEHOLDER):
    raise SystemExit('https.private_key is unset or still the placeholder')
if https_cfg and not os.path.isfile(key):
    raise SystemExit('https.private_key does not exist on the host: %s' % key)

Prevention

Always edit certificate and private_key together when enabling https
Verify cert/key pair match before running install
Automate cert rotation to update both harbor.yml entries

When it happens

Trigger: harbor.yml has 'https:' enabled and 'private_key:' left as '/your/certificate/path' or an empty value. Fires only after the certificate check (error 21) already passed, i.e. the certificate was fixed but the key was not.

Common situations: Half-finished edits: users replace the certificate path but leave the key placeholder; copy-paste configs where both paths still point at the sample; certificate renewed via script that only updates cert path.

Related errors

AI-assisted analysis of goharbor/harbor@7b2fd08cc5 (2026-08-16). Data as JSON: /api/errors/ad884fc5803ceb05. Report an issue: GitHub.