juicedata/juicefs · error

invalid endpoint: %s

Error message

invalid endpoint: %s

What it means

newKS3 in pkg/object/ks3.go parses the endpoint host as <bucket>.<region-host>; it splits the host on '.' and requires at least two labels. When the host has fewer than two dot-separated labels (e.g. 'localhost' or a bare hostname), the constructor cannot derive a bucket and region, so it rejects the endpoint.

Source

Thrown at pkg/object/ks3.go:385

	"cn-guangzhou": "GUANGZHOU",
	"cn-qingdao":   "QINGDAO",
	"jr-beijing":   "JR_BEIJING",
	"jr-shanghai":  "JR_SHANGHAI",
	"":             "HANGZHOU",
	"cn-hk-1":      "HONGKONG",
	"rus":          "RUSSIA",
	"sgp":          "SINGAPORE",
}

func newKS3(endpoint, accessKey, secretKey, token string) (ObjectStorage, error) {
	if !strings.Contains(endpoint, "://") {
		endpoint = fmt.Sprintf("https://%s", endpoint)
	}
	uri, _ := url.ParseRequestURI(endpoint)
	ssl := strings.ToLower(uri.Scheme) == "https"
	hostParts := strings.Split(uri.Host, ".")
	if len(hostParts) < 2 {
		return nil, fmt.Errorf("invalid endpoint: %s", endpoint)
	}
	bucket := hostParts[0]
	region := hostParts[1][3:]
	region = strings.TrimLeft(region, "-")
	var pathStyle bool = defaultPathStyle()
	if strings.HasSuffix(uri.Host, "ksyun.com") || strings.HasSuffix(uri.Host, "ksyuncs.com") {
		region = strings.TrimSuffix(region, "-internal")
		region = ks3Regions[region]
		pathStyle = false
	} else if envRegion := os.Getenv("AWS_REGION"); envRegion != "" {
		region = envRegion
	}
	if region == "" {
		region = "us-east-1"
	}

	var err error
	accessKey, err = url.PathUnescape(accessKey)

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Use a full virtual-host-style endpoint with the bucket prefix and a multi-label host, e.g. 'mybucket.ks3-cn-beijing.ksyuncs.com'.
2. If testing locally, use a hostname with at least one dot (e.g. 'ks3.local') and make it resolvable via /etc/hosts.
3. Verify the endpoint URL is complete and not truncated by shell quoting or config parsing.

Example fix

// before
createStorage("ks3", "localhost", ak, sk)
// after
createStorage("ks3", "mybucket.ks3-cn-beijing.ksyuncs.com", ak, sk)

func validKS3Endpoint(ep string) bool {
	host := ep
	if i := strings.Index(host, "://"); i >= 0 { host = host[i+3:] }
	if i := strings.IndexAny(host, "/?"); i >= 0 { host = host[:i] }
	return len(strings.Split(host, ".")) >= 2
}

store, err := newKS3(endpoint, ak, sk, "")
if err != nil {
	if strings.Contains(err.Error(), "invalid endpoint") {
		log.Fatalf("endpoint %q must be virtual-host style: bucket.region-host", endpoint)
	}
	return err
}

When it happens

Trigger: Creating a KS3 object store with an endpoint whose host has no dot, e.g. 'ks3://bucket@localhost/' or a bare hostname without a domain, or an endpoint missing the bucket prefix entirely.

Common situations: Local testing against a KS3-compatible proxy on localhost; typo where the bucket label is dropped ('ks3.cn-north-1.ksyuncs.com' without the leading bucket); using a Unix host alias instead of an FQDN.

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

• Invalid endpoint: %v, error: %v
• illegal value for parameter 'ranger-rest-url': " + url
• object storage: %s
• Invalid endpoint: %v, error: %v
• Invalid endpoint: %v

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