juicedata/juicefs · error · ValueError

binary mode doesn't take an errors argument

Error message

binary mode doesn't take an errors argument

What it means

juicefs.open() mimics Python's built-in open(). When the mode contains 'b' (binary), text-layer parameters like encoding and errors are meaningless, so the library raises ValueError('binary mode doesn't take an errors argument') when a non-falsy errors argument is passed together with binary mode.

Source

Thrown at sdk/python/juicefs/juicefs/juicefs.py:227

            if c in 'rwxa':
                cnt += 1
                if c == 'r':
                    flag |= MODE_READ
                else:
                    flag |= MODE_WRITE
            elif c == '+':
                flag |= MODE_READ | MODE_WRITE
            elif c not in 'tb':
                raise ValueError(f'invalid mode: {mode}')
        if cnt != 1:
            raise ValueError('must have exactly one of create/read/write/append mode')
        if 'b' in mode:
            if 't' in mode:
                raise ValueError("can't have text and binary mode at once")
            if encoding:
                raise ValueError("binary mode doesn't take an encoding argument")
            if errors:
                raise ValueError("binary mode doesn't take an errors argument")
        else:
            if not encoding:
                encoding = locale.getpreferredencoding(False).lower()
            if not errors:
                errors = 'strict'
            codecs.lookup(encoding)

        size = 0
        if 'x' in mode:
            fd = self.lib.jfs_create(c_int64(_tid()), c_int64(self.h), _bin(path), c_uint16(0o666), c_uint16(self.umask))
        else:
            try:
                sz = c_uint64()
                fd = self.lib.jfs_open_posix(c_int64(_tid()), c_int64(self.h), _bin(path), byref(sz), c_int32(flag))
                if 'w' in mode:
                    self.lib.jfs_ftruncate(c_int64(_tid()), fd, c_uint64(0))
                else:
                    size = sz.value

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Remove the errors argument when opening in binary mode
2. Switch to text mode ('r'/'rt') if you need errors handling
3. Handle decoding errors explicitly after reading bytes (data.decode('utf-8', errors='ignore'))

Example fix

// before
f = juicefs.open('/mnt/jfs/file', 'rb', errors='ignore')
// after
f = juicefs.open('/mnt/jfs/file', 'rb')
# or for text handling:
f = juicefs.open('/mnt/jfs/file', 'r', errors='ignore')

if 'b' in mode and errors:
    raise ValueError('pass errors only in text mode')

def is_binary_mode(mode: str) -> bool:
    return 'b' in mode

When it happens

Trigger: Calling juicefs.open(path, 'rb', errors='ignore'), or opening with any mode containing 'b' while supplying a truthy errors value (including errors=None is fine, but '' / 'strict' / 'ignore' trigger it).

Common situations: Porting code from text mode to binary mode after decoding issues; copy-pasting open(path, 'rb', errors='replace') from text-mode examples; wrapping a generic file-open helper that always forwards errors.

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

• invalid mode: {mode}
• must have exactly one of create/read/write/append mode
• can't have text and binary mode at once
• binary mode doesn't take an encoding argument
• invalid whence ({whence}, should be {os.SEEK_SET}, {os.SEEK_

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