juicedata/juicefs · error

invalid worker address %s: %s

Error message

invalid worker address %s: %s

What it means

startManager parses the first worker address as a URL by prefixing it with "ssh://". This error is returned when url.Parse rejects the resulting string, meaning the configured worker address is malformed (invalid characters, empty, bad host/port syntax). The distributed sync manager cannot start without at least one valid worker address.

Source

Thrown at pkg/sync/cluster.go:322

		srcDelayDelMu.Unlock()
		if checkpointMgr != nil {
			for key, state := range r.MultipartUploads {
				checkpointMgr.PutMultipartCheckpoint(key, state)
			}
			for _, key := range r.CompletedKeys {
				checkpointMgr.MarkCompleted(key)
			}
			for _, key := range r.FailedKeys {
				checkpointMgr.MarkFailed(key)
			}
		}
		logger.Debugf("receive stats %+v from %s", r, req.RemoteAddr)
		_, _ = w.Write([]byte("OK"))
	})
	var addr string
	u, err := url.Parse("ssh://" + config.Workers[0])
	if err != nil {
		return "", fmt.Errorf("invalid worker address %s: %s", config.Workers[0], err)
	}
	if config.ManagerAddr != "" {
		addr = config.ManagerAddr
		if strings.HasPrefix(addr, ":") || strings.Contains(addr, "0.0.0.0") {
			ip, err := utils.GetLocalIp(net.JoinHostPort(u.Host, "22"))
			if err != nil {
				return "", fmt.Errorf("get local ip: %s", err)
			}
			addr = ip + addr
		}
	} else {
		ip, err := utils.GetLocalIp(net.JoinHostPort(u.Host, "22"))
		if err != nil {
			return "", fmt.Errorf("not found local ip: %s", err)
		}
		logger.Debugf("Use local ip %s", ip)
		addr = ip
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Check the --worker argument for typos and invalid characters; repeat the flag for each worker instead of using separators
2. Wrap IPv6 addresses in brackets, e.g. --worker "ssh://[::1]:2222"
3. Quote the argument in the shell to avoid splitting/quote artifacts

Example fix

// before (invalid)
juicefs sync --worker host1,host2 src dst
// after
juicefs sync --worker host1 --worker host2 src dst

// Validate worker addresses before invoking sync
for _, w := range workers {
	if _, err := url.Parse("ssh://" + w); err != nil {
		return fmt.Errorf("bad worker address %q: %w", w, err)
	}
}

When it happens

Trigger: Running `juicefs sync --worker <addr> src dst` where the --worker value (config.Workers[0]) contains characters invalid in a URL host/port — e.g. spaces, stray brackets, "host:port:extra", or an empty string.

Common situations: Typo in worker hostnames on the command line; pasting a comma- or space-separated list instead of repeating --worker; IPv6 addresses not wrapped in brackets; shell quoting issues.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• url parse %s: %s
• redis parse %s: %s
• parse %s: %s
• Invalid endpoint: %v, error: %v
• parse url %s failed: %s

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