What causes "unescape access key: %s" in juicedata/juicefs?

Remove or correctly encode the stray '%' in the access key ('%' may appear only as %XX hex escapes).

unescape access key: %s

Error message

unescape access key: %s

What it means

newKS3 percent-decodes the access key with url.PathUnescape so URL-escaped credentials are restored. This error wraps a PathUnescape failure, meaning the access key contains a malformed escape sequence such as a stray '%' not followed by two hex digits.

Source

Thrown at pkg/object/ks3.go:405

	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)
	if err != nil {
		return nil, fmt.Errorf("unescape access key: %s", err)
	}
	secretKey, err = url.PathUnescape(secretKey)
	if err != nil {
		return nil, fmt.Errorf("unescape secret key: %s", err)
	}
	awsConfig := &aws.Config{
		Region:           region,
		Endpoint:         strings.SplitN(uri.Host, ".", 2)[1],
		DisableSSL:       !ssl,
		HTTPClient:       httpClient,
		S3ForcePathStyle: pathStyle,
		Credentials:      credentials.NewStaticCredentials(accessKey, secretKey, token),
	}

	return &ks3{bucket: bucket, s3: s3.New(awsConfig)}, nil
}

func init() {

View on GitHub (pinned to c9a67b23e8)

Solutions

Remove or correctly encode the stray '%' in the access key ('%' may appear only as %XX hex escapes).
Pass the raw, un-escaped access key; escaping is only needed inside URL components.
If the key genuinely contains '%', percent-encode it as %25 so PathUnescape yields the literal character.

Example fix

// before
accessKey := "AKIA100%"
// after
accessKey := "AKIA100%25" // or use the raw key without URL escaping

Defensive patterns

Strategy: validation

Validate before calling

func validPctEncoded(s string) bool {
	for i := 0; i < len(s); i++ {
		if s[i] == '%' {
			if i+2 >= len(s) || !isHex(s[i+1]) || !isHex(s[i+2]) { return false }
			i += 2
		}
	}
	return true
}

Try / catch

if _, err := url.PathUnescape(accessKey); err != nil {
	return fmt.Errorf("access key is not valid percent-encoding: %w", err)
}

Prevention

Pass raw credentials, not URL-escaped ones, when the source is not a URL.
Percent-encode literal '%' as %25 whenever credentials are embedded in a URL.
Store credentials in env vars or a secrets file instead of connection strings.

When it happens

Trigger: Passing an access key containing an invalid percent-escape (e.g. 'abc%zz' or '100%') to newKS3 through the KS3 storage configuration.

Common situations: Credentials pasted from a URL where '%' appeared literally; double-encoding mistakes when building the config string.

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

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