juicedata/juicefs · error

put encode file failed

Error message

put encode file failed: %s

What it means

objbench's 'special key' case puts an object whose key contains UTF-8 multibyte characters, JSON braces, a unit-separator (\u001F) and percent-encoded text, wrapping any Put failure with this message. It verifies the backend can store keys that need special encoding.

Solutions

1. Read the wrapped backend error for the root cause
2. Verify the backend supports arbitrary UTF-8 (and control-char) key encodings
3. Check the driver's key URL-escaping implementation
4. If the backend genuinely can't support such keys, treat this case as an expected limitation

// check key for characters the backend may reject
key := "测试编码文件" + `{"name":"juicefs"}` + string('\u001F') + "%uFF081%uFF09.jpg"
// probe put before real usage
if err := blob.Put(ctx, key, bytes.NewReader(nil)); err != nil { /* unsupported key */ }
_ = blob.Delete(ctx, key)

if err := blob.Put(ctx, key, r); err != nil {
    return fmt.Errorf("put encode file failed: %s", err)
}

When it happens

Trigger: `blob.Put(ctx, "测试编码文件{...}\u001F%uFF081%uFF09.jpg", ...)` returns an error — the backend rejects the key characters or the request fails.

Common situations: Backends that reject unicode/control characters in keys; misconfigured endpoints that mangle URL encoding; drivers that don't escape keys properly.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• list encode file failed: expect key
• list encode file failed
• put `/` suffixed object failed
• 1. ALL objects in the data storage
• apply object action failed in inode

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

Appendix: source

Thrown at cmd/objbench.go:980

		}()

		if objs, err := listAll(ctx, blob, "hashKey", "", int64(keyTotal)); err != nil {
			return fmt.Errorf("list failed: %s", err)
		} else {
			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++ {

View on GitHub (pinned to c9a67b23e8)