juicedata/juicefs · error

list encode file failed: expect key %s, but got %s

Error message

list encode file failed: expect key %s, but got %s

What it means

When the special-key List succeeds and returns exactly one object, objbench verifies its key equals the original encoded key; a mismatch yields this message naming the expected and actual keys. It means the backend mangled the key (encoding/decoding bug) during put or list.

Source

Thrown at cmd/objbench.go:985

			for i := 0; i < keyTotal; i++ {
				if objs[i].Key() != sortedKeys[i] {
					return fmt.Errorf("the result for list is incorrect")
				}
			}
		}
		return nil
	})

	runCase("special key", func(blob object.ObjectStorage) error {
		key := "测试编码文件" + `{"name":"juicefs"}` + string('\u001F') + "%uFF081%uFF09.jpg"
		defer blob.Delete(ctx, key) //nolint:errcheck
		if err := blob.Put(ctx, key, bytes.NewReader([]byte("1"))); err != nil {
			return fmt.Errorf("put encode file failed: %s", err)
		} else {
			if resp, _, _, err := blob.List(ctx, "", "测试编码文件", "", "", 1, true); err != nil && err != utils.ErrNotSUP {
				return fmt.Errorf("list encode file failed %s", err)
			} else if len(resp) == 1 && resp[0].Key() != key {
				return fmt.Errorf("list encode file failed: expect key %s, but got %s", key, resp[0].Key())
			}
		}
		return nil
	})

	runCase("put a big object", func(blob object.ObjectStorage) error {
		fsize := 256 << 20
		buffL := 4 << 20
		buff := make([]byte, buffL)
		utils.RandRead(buff)
		count := int(math.Floor(float64(fsize) / float64(buffL)))
		content := make([]byte, fsize)
		for i := 0; i < count; i++ {
			copy(content[i*buffL:(i+1)*buffL], buff)
		}
		if err := blob.Put(ctx, key, bytes.NewReader(content)); err != nil {
			return err
		}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Compare the expected vs got keys in the message to identify which characters were mangled
2. Fix the driver's key escaping/unescaping logic
3. Check for proxies or backend settings that rewrite URL paths
4. Avoid percent-encoding normalization in the driver

resp, _, _, err := blob.List(ctx, "", "测试编码文件", "", "", 1, true)
if err == nil && len(resp) == 1 && resp[0].Key() != expectedKey {
    // key was mangled by driver or backend
}

When it happens

Trigger: `len(resp) == 1 && resp[0].Key() != key` in the special-key case — the stored key differs from the key that was put (e.g. double/under-escaping of '%uFF08', unicode, or \u001F).

Common situations: Drivers that don't escape percent sequences in keys; backends that normalize unicode (NFC/NFD); proxies that decode URL-encoded characters in key paths.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• put encode file failed: %s
• list encode file failed %s
• ceph: can't put empty file
• GOOGLE_CLOUD_PROJECT environment variable must be set
• object key cannot be empty

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