What causes "LdapConnect failed: %w" in juicedata/juicefs?

Make init tolerant: log the wrapped error and defer/omit TrustPosixOffset mapping instead of failing startup.

LdapConnect failed: %w

Error message

LdapConnect failed: %w

What it means

initializeTrustPosixOffsets (run at package init) opens an LDAP session with LdapConnect("") to enumerate trusted domains and their POSIX offsets. If the connection cannot be established, it wraps the failure as "LdapConnect failed: %w". Because this runs during init on Windows, a failure here can abort startup of the SID/POSIX mapping machinery.

Source

Thrown at pkg/win/sid.go:179

	cnt2 := sid2.SubAuthorityCount()
	if cnt1+1 != cnt2 {
		return false
	}

	for i := uint8(0); i < cnt1; i++ {
		if sid1.SubAuthority(uint32(i)) != sid2.SubAuthority(uint32(i)) {
			return false
		}
	}

	return true
}

// initializeTrustPosixOffsets queries LDAP and sets TrustPosixOffset for each trusted domain.
func initializeTrustPosixOffsets() error {
	handle, err := LdapConnect("") // empty string means default server
	if err != nil {
		return fmt.Errorf("LdapConnect failed: %w", err)
	}
	defer LdapClose(handle)

	defaultNC, err := LdapGetDefaultNamingContext(handle)
	if err != nil {
		return fmt.Errorf("LdapGetDefaultNamingContext failed: %w", err)
	}

	// For each trusted domain, get trustPosixOffset
	for i := range trustedDomains {
		domain := windows.UTF16PtrToString(trustedDomains[i].DnsDomainName)
		offsetStr, err := LdapGetTrustPosixOffset(handle, defaultNC, domain)
		if err == nil {
			if val, err := strconv.ParseUint(offsetStr, 10, 32); err == nil {
				trustedDomains[i].TrustPosixOffset = uint32(val)
			}
		}
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

Make init tolerant: log the wrapped error and defer/omit TrustPosixOffset mapping instead of failing startup.
Ensure the host is domain-joined and a DC is reachable (nltest /dsgetdc:, nslookup SRV _ldap._tcp).
Run the process after network initialization; avoid eager LDAP at package init.
Open firewall paths to the DC for LDAP (389/636) or connect over VPN.
Provide an explicit DC hostname to LdapConnect instead of relying on the default server.

Example fix

// before
func init() {
    if err := initializeTrustPosixOffsets(); err != nil {
        panic(err) // or log.Fatal
    }
}
// after
func init() {
    if err := initializeTrustPosixOffsets(); err != nil {
        log.Printf("trust posix offsets unavailable: %v", err) // degrade gracefully
    }
}

Defensive patterns

Strategy: try-catch

Validate before calling

// before enabling the feature, check:
// nltest /dsgetdc:domain.local  AND  Test-ComputerSecureChannel

Try / catch

if err := initializeTrustPosixOffsets(); err != nil {
    log.Printf("trust posix offsets disabled: %v", err) // don't fail init
}

Prevention

Avoid fatal LDAP errors in package init; degrade gracefully instead.
Guard AD-dependent initialization behind a reachability probe.
Document domain-join and DC-connectivity prerequisites for Windows deployments.
Support an explicit DC address config to bypass default discovery.

When it happens

Trigger: Package init calls initializeTrustPosixOffsets on a machine where LdapConnect fails — no reachable DC, non-domain-joined host, DNS failure, or blocked LDAP port.

Common situations: Deploying on workgroup machines or VMs without line-of-sight to a domain controller; laptops off the corporate network/VPN; firewalls blocking port 389; running before network is up during early boot.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/99277bd613f875cc. Report an issue: GitHub.