goharbor/harbor · error · Exception

Error: must set log endpoint host to enable external host

Error message

Error: must set log endpoint host to enable external host

What it means

Thrown by validate() in make/photon/prepare/utils/configs.py when harbor.yml configures an external syslog endpoint ('log.external_endpoint') but its 'host' is present and empty. Harbor forwards container logs to this endpoint via a syslog driver, and an empty host would produce an unusable syslog target, so prepare refuses to continue.

Source

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

    # 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)))

    # original is registry_storage_provider_config
    storage_provider_config = conf.get("storage_provider_config")
    if storage_provider_name != "filesystem":
        if storage_provider_config == "":
            raise Exception(
                "Error: no provider configurations are provided for provider %s" % storage_provider_name)

View on GitHub (pinned to 7b2fd08cc5)

Solutions

1. Set 'log.external_endpoint.host:' to the FQDN or IP of the syslog receiver, e.g. logs.example.com
2. Set the matching 'port:' and 'protocol:' (see related checks) in the same block
3. If external log shipping is not wanted, comment out or delete the whole 'external_endpoint:' block so local logging is used
4. Re-run ./install.sh

Example fix

# harbor.yml (before)
log:
  level: info
  external_endpoint:
    protocol: tcp
    host:
    port: 5140

# harbor.yml (after)
log:
  level: info
  external_endpoint:
    protocol: tcp
    host: logs.example.com
    port: 5140

ep = (cfg.get('log') or {}).get('external_endpoint')
if ep is not None and not ep.get('host'):
    raise SystemExit('log.external_endpoint.host must be set when external_endpoint is configured')

When it happens

Trigger: harbor.yml contains a 'log:' section with 'external_endpoint:' uncommented and 'host:' left blank (empty string). parse_yaml_config sets config_dict['log_ep_host'] to '', and the check ('log_ep_host' in conf) and not conf['log_ep_host'] fires.

Common situations: Users enable external_endpoint to ship logs to Paperstack/splunk/syslog but forget the host, or comment the host value while keeping the key; YAML indentation mistakes that null out host.

Related errors

• Error: must set log endpoint port to enable external host
• Protocol in external log endpoint must be one of 'udp' or 't
• log level must be one of debug, info, warning, error, fatal
• missing logger config of job service
• missing logger config of job

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