grpc/grpc-java · error · ZipException

Unsupported compression method

Error message

Unsupported compression method

What it means

GzipInflatingBuffer decompresses gzip-wrapped gRPC message streams. During header parsing (processHeader), after verifying the GZIP magic number, it checks that the compression method byte equals 8 (the only method defined by RFC 1952, 'deflate'). Any other byte means the stream is not standard gzip, so a ZipException('Unsupported compression method') is thrown.

Source

Thrown at core/src/main/java/io/grpc/internal/GzipInflatingBuffer.java:326

      }
    }
    // If we finished a gzip block, check if we have enough bytes to read another header
    isStalled =
        !madeProgress
            || (state == State.HEADER && gzipMetadataReader.readableBytes() < GZIP_HEADER_MIN_SIZE);

    return bytesRead;
  }

  private boolean processHeader() throws ZipException {
    if (gzipMetadataReader.readableBytes() < GZIP_HEADER_MIN_SIZE) {
      return false;
    }
    if (gzipMetadataReader.readUnsignedShort() != GZIP_MAGIC) {
      throw new ZipException("Not in GZIP format");
    }
    if (gzipMetadataReader.readUnsignedByte() != 8) {
      throw new ZipException("Unsupported compression method");
    }
    gzipHeaderFlag = gzipMetadataReader.readUnsignedByte();
    gzipMetadataReader.skipBytes(6 /* remaining header bytes */);
    state = State.HEADER_EXTRA_LEN;
    return true;
  }

  private boolean processHeaderExtraLen() {
    if ((gzipHeaderFlag & HEADER_EXTRA_FLAG) != HEADER_EXTRA_FLAG) {
      state = State.HEADER_NAME;
      return true;
    }
    if (gzipMetadataReader.readableBytes() < UNSIGNED_SHORT_SIZE) {
      return false;
    }
    headerExtraToRead = gzipMetadataReader.readUnsignedShort();
    state = State.HEADER_EXTRA;
    return true;

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Verify the sender actually produces gzip (method byte 8) — dump the first bytes of the payload and confirm 1f 8b 08
2. Align the gRPC compression registry on both peers (use the same encoding, e.g. gzip on both sides)
3. Remove/fix proxies that rewrite or corrupt response bodies
4. Capture the stream and validate it with `gzip -t` to rule out corruption upstream

Example fix

// before: sending raw deflate bytes with gzip Content-Encoding
Deflater deflater = new Deflater();
byte[] body = compress(deflater, data);
// after: use a real GZIPOutputStream so the header declares method 8
ByteArrayOutputStream bos = new ByteArrayOutputStream();
try (GZIPOutputStream gz = new GZIPOutputStream(bos)) {
  gz.write(data);
}
byte[] body = bos.toByteArray();

// validate gzip payload before sending
if (payload.length < 3 || payload[0] != 0x1f || payload[1] != (byte)0x8b) throw new IllegalArgumentException("not gzip");
if ((payload[2] & 0xff) != 8) throw new IllegalArgumentException("compression method must be 8 (deflate)");

static boolean isGzipDeflate(byte[] b) {
  return b != null && b.length >= 3 && b[0] == 0x1f && b[1] == (byte)0x8b && (b[2] & 0xff) == 8;
}

try { call(...); } catch (StatusRuntimeException e) {
  if (e.getCause() instanceof ZipException && e.getCause().getMessage().contains("Unsupported compression method")) {
    // renegotiate compression or fall back to identity encoding
  } else throw e;
}

When it happens

Trigger: A compressed gRPC message stream's first bytes decode to a valid GZIP magic (0x1f 0x8b) but the third byte (compression method) is not 8 — e.g. the payload was produced by a different compression scheme or is otherwise corrupted/truncated in the header.

Common situations: Client and server disagree on compression; a proxy or intermediary mangles/replaces the compressed body; a custom marshaller writes raw deflate or zstd bytes mislabeled as gzip; truncated or bit-flipped data from a broken connection.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Not in GZIP format
• Corrupt GZIP header
• Inflater data format exception:
• Corrupt GZIP trailer
• No ALTS context information found

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/579698e1642046cc. Report an issue: GitHub.