goharbor/harbor · error · Exception

Please specify hostname

Error message

Please specify hostname

What it means

Thrown by Harbor's prepare-time validator (make/photon/prepare/utils/configs.py, validate()) when the harbor.yml 'hostname' still equals the template placeholder 'reg.mydomain.com'. The hostname builds Harbor's public URL, registry endpoints, and generated certificates, so a placeholder value would break every push/pull and browser redirect. The prepare step aborts before any container is started.

Source

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

from models import InternalTLS, Metric, Trace, PurgeUpload, Cache, Core
from utils.misc import generate_random_string, owner_can_read, other_can_read

# NOTE: https://golang.org/pkg/database/sql/#DB.SetMaxIdleConns
default_db_max_idle_conns = 2
# NOTE: https://golang.org/pkg/database/sql/#DB.SetMaxOpenConns
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' ")

View on GitHub (pinned to 7b2fd08cc5)

Solutions

1. Edit harbor.yml and set 'hostname:' to the real FQDN or IP that clients will use to reach Harbor
2. If Harbor sits behind a load balancer or proxy, use that public address
3. Do not use 127.0.0.1 (rejected by the adjacent check at configs.py:22)
4. Re-run ./install.sh (or ./prepare) and confirm the error is gone

Example fix

# harbor.yml (before)
hostname: reg.mydomain.com

# harbor.yml (after)
hostname: harbor.example.com

# pre-flight check before running install.sh
import yaml
cfg = yaml.safe_load(open('harbor.yml'))
h = cfg.get('hostname')
if not h or h in ('reg.mydomain.com', '127.0.0.1'):
    raise SystemExit('Set a real hostname in harbor.yml before installing')

When it happens

Trigger: Running ./install.sh or the prepare command with harbor.yml where 'hostname: reg.mydomain.com' was left unchanged from harbor.yml.tmpl. The check is an exact string comparison, so any other value passes (a sibling check rejects 127.0.0.1).

Common situations: Fresh installs where only harbor_admin_password was edited; copying the template to harbor.yml in CI and forgetting the hostname; following tutorials that keep the sample file.

Related errors

• Protocol in external log endpoint must be one of 'udp' or 't
• Error: storage driver %s is not supported, only the followin
• Error: no provider configurations are provided for provider
• log level must be one of debug, info, warning, error, fatal
• File {} not exist

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