{"record":{"id":"db9b42c1998dc362","repo":"goharbor/harbor","slug":"ldap-server-network-timeout","errorCode":null,"errorMessage":"ldap server network timeout","messagePattern":"ldap server network timeout","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/pkg/ldap/ldap.go","lineNumber":45,"sourceCode":"\n\t\"github.com/goharbor/harbor/src/lib/config/models\"\n\t\"github.com/goharbor/harbor/src/lib/log\"\n\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 {","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/goharbor/harbor/blob/7b2fd08cc568955cca339afeefab27372840d936/src/pkg/ldap/ldap.go#L27-L63","documentation":"Sentinel error returned by ldap.TestConfig when opening the connection fails with a go-ldap ErrorNetwork code: the LDAP server could not be reached at the configured URL within the connection timeout. It surfaces from POST /api/v2.0/ldap/ping and from any LDAP session open during login/sync.","triggerScenarios":"POST /api/v2.0/ldap/ping with an unreachable ldap_url — wrong host/port, service down, DNS failure, firewall/security-group blocking egress from the Harbor core container, or ldap_connection_timeout set too small for a slow WAN link (default DialURL timeout).","commonSituations":"Harbor running in Kubernetes/Docker where the core pod cannot reach the DC (network policy, CIDR restrictions); AD behind a load balancer whose health check is down; port 636 vs 389 mix-ups so TLS talks to a plain port; container DNS different from the admin's workstation DNS.","solutions":["From inside the Harbor core container, verify reachability: nc -vz <ldap_host> <port> (389 for ldap, 636 for ldaps).","Fix ldap_url scheme/port — let Harbor default them (ldap://host → 389, ldaps://host → 636) instead of guessing.","If the link is genuinely slow, raise ldap_connection_timeout via PUT /api/v2.0/configurations.","Check firewall/NAT rules and DNS resolution from the container network."],"exampleFix":"# before: port 389 open on server, but url says ldaps\ncurl -X POST https://harbor/api/v2.0/ldap/ping -d '{\"url\": \"ldaps://ad.example.com\"}'\n# after\ncurl -X POST https://harbor/api/v2.0/ldap/ping -d '{\"url\": \"ldap://ad.example.com\"}'","handlingStrategy":"retry","validationCode":"// Preflight reachability from where Harbor core runs\nconn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, port), 3*time.Second)\nif err != nil { /* fix URL/firewall/DNS before pinging LDAP */ }\nconn.Close()","typeGuard":"func isLdapNetworkTimeout(err error) bool { return errors.Is(err, ldap.ErrLDAPServerTimeout) }","tryCatchPattern":"Retry with backoff (e.g. 3 attempts, 2s/5s) only for errors.Is(err, ldap.ErrLDAPServerTimeout); on persistent failure, stop and diagnose network (DNS, firewall, LB health) instead of retrying forever.","preventionTips":["Monitor TCP reachability to the directory's 389/636 from the Harbor core network as a synthetic check.","Pin ldap_url to a stable LB VIP, and set ldap_connection_timeout generously for WAN links.","Keep container DNS and firewall rules in sync when the directory moves."],"tags":["ldap","network","timeout","connectivity","harbor"],"backgroundTag":null,"analyzedSha":"7b2fd08cc568955cca339afeefab27372840d936","analyzedAt":"2026-08-16T00:00:10.961Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}