goharbor/harbor · error · Exception

Error: The protocol is https but attribute ssl_cert is not s

Error message

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

What it means

Thrown by validate() in make/photon/prepare/utils/configs.py when harbor.yml declares 'protocol: https' but the certificate path is empty or still the placeholder '/your/certificate/path' (default_https_cert_path). Harbor needs a real server certificate to configure the nginx proxy and derive internal TLS material, so HTTPS cannot proceed without it. The message says ssl_cert because it mirrors the old harbor.cfg attribute name.

Source

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

default_db_max_open_conns = 0
default_https_cert_path = '/your/certificate/path'
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" % (

View on GitHub (pinned to 7b2fd08cc5)

Solutions

Set 'https.certificate:' in harbor.yml to the absolute path of an existing PEM certificate on the Docker host, e.g. /data/cert/server.crt
Verify the file exists on the host: ls -l /data/cert/server.crt
If you do not have certificates yet, generate self-signed ones with openssl or keep the whole 'https:' block commented out to install over http (insecure, warned)
Re-run ./install.sh

Example fix

# harbor.yml (before)
https:
  port: 443
  certificate: /your/certificate/path
  private_key: /your/certificate/path

# harbor.yml (after)
https:
  port: 443
  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 {}
cert = https_cfg.get('certificate', '')
if https_cfg and (not cert or cert == PLACEHOLDER):
    raise SystemExit('https.certificate is unset or still the placeholder')
import os
if https_cfg and not os.path.isfile(cert):
    raise SystemExit('https.certificate does not exist on the host: %s' % cert)

Prevention

Replace every '/your/certificate/path' placeholder when enabling https
Use absolute host paths; prepare resolves them inside its container against the host filesystem
Prepare certificates before flipping Harbor to https

When it happens

Trigger: harbor.yml has the 'https:' block uncommented and 'certificate:' left as '/your/certificate/path' (or an empty value) when the config dict reaches validate(). The check is: not conf.get('cert_path') or conf['cert_path'] == '/your/certificate/path'.

Common situations: Users uncomment https but never replace the sample paths; someone comments out only the certificate line while keeping the key line; upgrades from http to https where the placeholder was never touched.

Related errors

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