What causes "Error: The path for certificate key: %s is invalid" in goharbor/harbor?

Verify the path on the Harbor host: ls -l

Error: The path for certificate key: %s is invalid

Error message

Error: The path for certificate key: %s is invalid

What it means

Thrown by the legacy validator in make/photon/prepare/utils/misc.py when harbor.cfg sets ui_url_protocol = https and provides ssl_cert_key, but os.path.isfile(cert_key_path) is false - the configured private key path does not exist as a regular file where prepare looks for it. The same check runs for the certificate one line above; this raise is specifically the key path.

Source

Thrown at make/photon/prepare/utils/misc.py:35


def validate(conf, **kwargs):
    # Protocol validate
    protocol = conf.get("configuration", "ui_url_protocol")
    if protocol == "https":
        if not conf.has_option("configuration", "ssl_cert"):
            raise Exception(
                "Error: The protocol is https but attribute ssl_cert is not set")
        cert_path = conf.get("configuration", "ssl_cert")
        if not os.path.isfile(cert_path):
            raise Exception(
                "Error: The path for certificate: %s is invalid" % cert_path)
        if not conf.has_option("configuration", "ssl_cert_key"):
            raise Exception(
                "Error: The protocol is https but attribute ssl_cert_key is not set")
        cert_key_path = conf.get("configuration", "ssl_cert_key")
        if not os.path.isfile(cert_key_path):
            raise Exception(
                "Error: The path for certificate key: %s is invalid" % cert_key_path)

    # Storage validate
    valid_storage_drivers = ["filesystem",
                             "azure", "gcs", "s3", "swift", "oss"]
    storage_provider_name = conf.get(
        "configuration", "registry_storage_provider_name").strip()
    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)))

    storage_provider_config = conf.get(
        "configuration", "registry_storage_provider_config").strip()
    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

Verify the path on the Harbor host: ls -l <ssl_cert_key value>
Fix the ssl_cert_key value in harbor.cfg to the absolute path of the existing key file
Confirm the key is a file, not a directory or symlink to a missing target
Re-run prepare/install

Example fix

# harbor.cfg (before)
ssl_cert_key = /cert/server.key      # file not there

# after
ssl_cert_key = /data/cert/server.key  # exists: -rw------- 1 10000 10000

Defensive patterns

Strategy: validation

Validate before calling

import configparser, os
conf = configparser.ConfigParser()
conf.read('harbor.cfg')
if conf.get('configuration', 'ui_url_protocol') == 'https':
    key = conf.get('configuration', 'ssl_cert_key')
    if not os.path.isfile(key):
        raise SystemExit('ssl_cert_key path invalid: %s' % key)

Prevention

Copy TLS material to the host and verify with ls before flipping to https
Use absolute paths in harbor.cfg
Re-check paths after migrating harbor.cfg between servers

When it happens

Trigger: harbor.cfg has 'ssl_cert_key = /cert/server.key' but the file is absent, is a directory, uses a relative path, or lives at a location not visible to the prepare environment. os.path.isfile returns False and the error embeds the offending path.

Common situations: Certificates not copied to the Harbor host before install; typos in paths; restoring harbor.cfg backups after the certs were rotated away; paths valid on an old server but different on the new one.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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