What causes "stream_decompress mode must be gzip or deflate" in arduino/Arduino?

Pass exactly 'gzip' or 'deflate' (lowercase) as mode.

arduino/Arduino · error · ValueError

stream_decompress mode must be gzip or deflate

Error message

stream_decompress mode must be gzip or deflate

What it means

stream_decompress decompresses a chunk iterator using zlib, but only supports 'gzip' and 'deflate' transfer encodings. Any other mode string is rejected with this ValueError before a zlib decompress object is created.

Source

Thrown at arduino-core/src/processing/app/i18n/python/requests/utils.py:358

            tried_encodings.append(encoding)

    # Fall back:
    try:
        return str(r.content, encoding, errors='replace')
    except TypeError:
        return r.content


def stream_decompress(iterator, mode='gzip'):
    """Stream decodes an iterator over compressed data

    :param iterator: An iterator over compressed data
    :param mode: 'gzip' or 'deflate'
    :return: An iterator over decompressed data
    """

    if mode not in ['gzip', 'deflate']:
        raise ValueError('stream_decompress mode must be gzip or deflate')

    zlib_mode = 16 + zlib.MAX_WBITS if mode == 'gzip' else -zlib.MAX_WBITS
    dec = zlib.decompressobj(zlib_mode)
    try:
        for chunk in iterator:
            rv = dec.decompress(chunk)
            if rv:
                yield rv
    except zlib.error:
        # If there was an error decompressing, just return the raw chunk
        yield chunk
        # Continue to return the rest of the raw data
        for chunk in iterator:
            yield chunk
    else:
        # Make sure everything has been returned from the decompression object
        buf = dec.decompress(bytes())
        rv = buf + dec.flush()

View on GitHub (pinned to a0df6e0e83)

Solutions

Pass exactly 'gzip' or 'deflate' (lowercase) as mode.
If the response is brotli/zstd encoded, use a library that supports it (brotli/zstandard packages) instead of stream_decompress.
Normalize the mode before calling: mode = mode.lower(), and only if it is in ('gzip', 'deflate').
If the body is not compressed at all, skip decompression rather than passing an invalid mode.

Example fix

// before
stream_decompress(chunks, mode='GZIP')
# after
stream_decompress(chunks, mode='gzip')

Defensive patterns

Strategy: validation

Validate before calling

if mode not in ('gzip', 'deflate'):
    raise ValueError('unsupported encoding: %r' % mode)

Try / catch

try:
    out = stream_decompress(chunks, mode=enc)
except ValueError:
    out = chunks  # fall back to undecoded stream

Prevention

Normalize Content-Encoding to lowercase before dispatch
Only claim support for gzip/deflate in Accept-Encoding headers
Route brotli/zstd to dedicated decoders

When it happens

Trigger: Calling stream_decompress(iterator, mode=...) with a mode other than 'gzip' or 'deflate' (e.g. 'br', 'zstd', None, or a case variant like 'GZIP'), typically via stream_untransfer when decoding a streamed response body.

Common situations: Server sends a Content-Encoding the helper doesn't support (brotli, zstd) and callers pass it straight through; typo or wrong casing in the mode string; tests that call stream_decompress directly with an unsupported encoding.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of arduino/Arduino@a0df6e0e83 (2026-09-06). Data as JSON: /api/errors/1da593bfc32d9d84. Report an issue: GitHub.