goharbor/harbor · error

fail to ping LDAP server

Error message

fail to ping LDAP server

What it means

Sentinel error returned by ldap.TestConfig when opening the connection fails with any non-network error — typically a TLS failure on ldaps:// (certificate verification with ldap_verify_cert=true against an untrusted/internal CA) or a malformed LDAP URL (unknown scheme, unparseable host:port). It is the catch-all sibling of ErrLDAPServerTimeout for POST /api/v2.0/ldap/ping.

Source

Thrown at src/pkg/ldap/ldap.go:48

	"github.com/goharbor/harbor/src/pkg/ldap/model"
)

const pageSize = 1000

// ErrNotFound ...
var ErrNotFound = errors.New("entity not found")

// ErrEmptyPassword ...
var ErrEmptyPassword = errors.New("empty password")

// ErrInvalidCredential ...
var ErrInvalidCredential = errors.New("invalid credential")

// ErrLDAPServerTimeout ...
var ErrLDAPServerTimeout = errors.New("ldap server network timeout")

// ErrLDAPPingFail ...
var ErrLDAPPingFail = errors.New("fail to ping LDAP server")

// ErrDNSyntax ...
var ErrDNSyntax = errors.New("invalid DN syntax")

// ErrInvalidFilter ...
var ErrInvalidFilter = errors.New("invalid filter syntax")

// ErrEmptyBaseDN ...
var ErrEmptyBaseDN = errors.New("empty base dn")

// ErrEmptySearchDN ...
var ErrEmptySearchDN = errors.New("empty search dn")

// Session - define a LDAP session
type Session struct {
	basicCfg models.LdapConf
	groupCfg models.GroupConf
	ldapConn *goldap.Conn

View on GitHub (pinned to 7b2fd08cc5)

Solutions

1. Check Harbor core logs at ping time — the underlying TLS/x509 or URL-parse error is logged even though the API only says 'fail to ping LDAP server'.
2. Add the directory's CA to the core container trust store (or the os trusted certs mount) when using internal CA with ldaps.
3. As a stopgap set ldap_verify_cert=false (self-signed only; not for production).
4. Correct the URL format: scheme ldap|ldaps, plain host[:port], no path.

Example fix

# before: internal CA cert, verification on
curl -X POST https://harbor/api/v2.0/ldap/ping -d '{"url": "ldaps://ad.corp.local:636", "search_dn": "...", "search_password": "...", "verify_cert": true}'
# after: trust installed on host, or for self-signed labs only
curl -X POST https://harbor/api/v2.0/ldap/ping -d '{"url": "ldaps://ad.corp.local:636", "search_dn": "...", "search_password": "...", "verify_cert": false}'

// Go: preflight the ldaps URL exactly as Harbor core will
u, err := url.Parse(cfg.URL)
if u.Scheme != "ldap" && u.Scheme != "ldaps" { fail("scheme must be ldap or ldaps") }
if cfg.Scheme == "ldaps" && cfg.VerifyCert {
    _, err := tls.Dial("tcp", hostport, &tls.Config{ServerName: host}) // uses system roots
    if err != nil { fail("TLS trust problem: install the CA into the core container") }
}

func isLdapPingFail(err error) bool { return errors.Is(err, ldap.ErrLDAPPingFail) }

if errors.Is(err, ldap.ErrLDAPPingFail) {
    // NOT a network problem: read core logs for the real x509/URL-parse cause,
    // fix trust store or URL format, then re-ping; do not retry blindly
}

When it happens

Trigger: ldaps:// URL with a self-signed or internal-CA certificate while ldap_verify_cert is true; ldap_url with an unsupported scheme like "ldapx://" or an illegal host:port that fails parsing before dialing; SNI/hostname mismatch between the URL and the certificate.

Common situations: Internal AD with an enterprise CA whose root is not in the Harbor core container's trust bundle; staging LDAPS certs that expire unnoticed (x509: certificate has expired); TLS-terminating proxies in front of the directory; URLs pasted with trailing slashes or schemes that formatURL rejects.

Related errors

• Error: The protocol is https but attribute ssl_cert is not s
• invalid CA certificate: no valid certificates found in PEM d
• BAD_REQUEST
• empty password
• empty search dn

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