goharbor/harbor · error

ldap server network timeout

Error message

ldap server network timeout

What it means

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.

Source

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

	"github.com/goharbor/harbor/src/lib/config/models"
	"github.com/goharbor/harbor/src/lib/log"
	"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 {

View on GitHub (pinned to 7b2fd08cc5)

Solutions

1. From inside the Harbor core container, verify reachability: nc -vz <ldap_host> <port> (389 for ldap, 636 for ldaps).
2. Fix ldap_url scheme/port — let Harbor default them (ldap://host → 389, ldaps://host → 636) instead of guessing.
3. If the link is genuinely slow, raise ldap_connection_timeout via PUT /api/v2.0/configurations.
4. Check firewall/NAT rules and DNS resolution from the container network.

Example fix

# before: port 389 open on server, but url says ldaps
curl -X POST https://harbor/api/v2.0/ldap/ping -d '{"url": "ldaps://ad.example.com"}'
# after
curl -X POST https://harbor/api/v2.0/ldap/ping -d '{"url": "ldap://ad.example.com"}'

// Preflight reachability from where Harbor core runs
conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, port), 3*time.Second)
if err != nil { /* fix URL/firewall/DNS before pinging LDAP */ }
conn.Close()

func isLdapNetworkTimeout(err error) bool { return errors.Is(err, ldap.ErrLDAPServerTimeout) }

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.

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• group does not exist
• a LDAP user group with same DN already exist
• the LDAP group DN is invalid
• BAD_REQUEST
• entity not found

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