{"record":{"id":"2af57047bc7858f2","repo":"goharbor/harbor","slug":"fail-to-ping-ldap-server","errorCode":null,"errorMessage":"fail to ping LDAP server","messagePattern":"fail to ping LDAP server","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/pkg/ldap/ldap.go","lineNumber":48,"sourceCode":"\t\"github.com/goharbor/harbor/src/pkg/ldap/model\"\n)\n\nconst pageSize = 1000\n\n// ErrNotFound ...\nvar ErrNotFound = errors.New(\"entity not found\")\n\n// ErrEmptyPassword ...\nvar ErrEmptyPassword = errors.New(\"empty password\")\n\n// ErrInvalidCredential ...\nvar ErrInvalidCredential = errors.New(\"invalid credential\")\n\n// ErrLDAPServerTimeout ...\nvar ErrLDAPServerTimeout = errors.New(\"ldap server network timeout\")\n\n// ErrLDAPPingFail ...\nvar ErrLDAPPingFail = errors.New(\"fail to ping LDAP server\")\n\n// ErrDNSyntax ...\nvar ErrDNSyntax = errors.New(\"invalid DN syntax\")\n\n// ErrInvalidFilter ...\nvar ErrInvalidFilter = errors.New(\"invalid filter syntax\")\n\n// ErrEmptyBaseDN ...\nvar ErrEmptyBaseDN = errors.New(\"empty base dn\")\n\n// ErrEmptySearchDN ...\nvar ErrEmptySearchDN = errors.New(\"empty search dn\")\n\n// Session - define a LDAP session\ntype Session struct {\n\tbasicCfg models.LdapConf\n\tgroupCfg models.GroupConf\n\tldapConn *goldap.Conn","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/goharbor/harbor/blob/7b2fd08cc568955cca339afeefab27372840d936/src/pkg/ldap/ldap.go#L30-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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'.","Add the directory's CA to the core container trust store (or the os trusted certs mount) when using internal CA with ldaps.","As a stopgap set ldap_verify_cert=false (self-signed only; not for production).","Correct the URL format: scheme ldap|ldaps, plain host[:port], no path."],"exampleFix":"# before: internal CA cert, verification on\ncurl -X POST https://harbor/api/v2.0/ldap/ping -d '{\"url\": \"ldaps://ad.corp.local:636\", \"search_dn\": \"...\", \"search_password\": \"...\", \"verify_cert\": true}'\n# after: trust installed on host, or for self-signed labs only\ncurl -X POST https://harbor/api/v2.0/ldap/ping -d '{\"url\": \"ldaps://ad.corp.local:636\", \"search_dn\": \"...\", \"search_password\": \"...\", \"verify_cert\": false}'","handlingStrategy":"validation","validationCode":"// Go: preflight the ldaps URL exactly as Harbor core will\nu, err := url.Parse(cfg.URL)\nif u.Scheme != \"ldap\" && u.Scheme != \"ldaps\" { fail(\"scheme must be ldap or ldaps\") }\nif cfg.Scheme == \"ldaps\" && cfg.VerifyCert {\n    _, err := tls.Dial(\"tcp\", hostport, &tls.Config{ServerName: host}) // uses system roots\n    if err != nil { fail(\"TLS trust problem: install the CA into the core container\") }\n}","typeGuard":"func isLdapPingFail(err error) bool { return errors.Is(err, ldap.ErrLDAPPingFail) }","tryCatchPattern":"if errors.Is(err, ldap.ErrLDAPPingFail) {\n    // NOT a network problem: read core logs for the real x509/URL-parse cause,\n    // fix trust store or URL format, then re-ping; do not retry blindly\n}","preventionTips":["Install internal directory CAs into the Harbor core container's trust bundle at deploy time.","Monitor certificate expiry on LDAPS endpoints.","Keep ldap_url shape simple: scheme + host[:port], letting Harbor default 389/636."],"tags":["ldap","tls","certificate","config","harbor"],"backgroundTag":null,"analyzedSha":"7b2fd08cc568955cca339afeefab27372840d936","analyzedAt":"2026-08-16T00:00:10.961Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}