juicedata/juicefs · error

put encode file failed: %s

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.

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)

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 %s
• list encode file failed: expect key %s, but got %s
• put `/` suffixed object failed: %s
• ceph: can't put empty file
• GOOGLE_CLOUD_PROJECT environment variable must be set

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