Prism adds Content-Encoding headers from spec but doesn't compress response body

[CristhianMotoche]

Context

When an OpenAPI spec defines Content-Encoding as a response header, Prism adds this header to mock responses but doesn't actually compress the response body. This causes HTTP clients to fail when attempting to decompress the uncompressed data.

Current Behavior

When an OpenAPI spec includes Content-Encoding as a response header with enum values like:

"headers": {
  "Content-Encoding": {
    "schema": {
      "type": "string",
      "enum": ["gzip", "deflate", "br", "compress"]
    }
  }
}

Prism randomly selects one of these enum values and adds it to the response headers, but the response body remains uncompressed. When HTTP clients (like Python's requests library) see the Content-Encoding header, they attempt to decompress the body and fail with:

zlib.error: Error -3 while decompressing data: incorrect header check

or

requests.exceptions.ContentDecodingError: ('Received response with content-encoding: gzip, but failed to decode it.')

Expected Behavior

Prism should not add Content-Encoding headers to responses unless it's actually compressing the response body. The Content-Encoding header in an OpenAPI spec is describing what the real API does - the mock server shouldn't blindly add it without implementing the actual compression.

Alternatively, Prism could compress the response body to match the header, but that seems unnecessary for a mock server (or maybe not 🤷 ).

Possible Workaround/Solution

Workaround 1: Remove Content-Encoding from the response headers in your OpenAPI spec when using with Prism.

Workaround 2: Use nginx (or another reverse proxy) in front of Prism to strip the Content-Encoding header:

location / {
  proxy_pass http://prism:4010;
  proxy_hide_header Content-Encoding;
}

Suggested Fix: Prism should ignore Content-Encoding when generating response headers, or at minimum, document that this header should not be included in OpenAPI specs used with Prism.

Steps to Reproduce

1. Create a minimal OpenAPI spec with Content-Encoding in response headers (see below)

2. Start Prism:

   npx @stoplight/prism-cli@5.15.10 mock -h 0.0.0.0 -p 4010 prism-minimal-bug-spec.json

3. Make requests with a client that supports decompression:

   import requests
   
   session = requests.Session()
   session.headers.update({'Accept-Encoding': 'gzip, deflate'})
   
   for i in range(10):
       try:
           r = session.get('http://localhost:4010/test')
           print(f"Run {i+1}: SUCCESS")
       except requests.exceptions.ContentDecodingError as e:
           print(f"Run {i+1}: FAILED - {e}")

4. Result: 100% of requests fail with decompression errors

Minimal OpenAPI Spec (prism-minimal-bug-spec.json):

{
  "openapi": "3.0.0",
  "info": {
    "title": "Minimal Prism Content-Encoding Bug",
    "version": "1.0.0"
  },
  "paths": {
    "/test": {
      "get": {
        "summary": "Test endpoint",
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "Content-Encoding": {
                "description": "The compression algorithm used",
                "schema": {
                  "type": "string",
                  "enum": ["gzip", "deflate", "br", "compress"]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Environment

• Prism Version: 5.14.2 and 5.15.10 (bug exists in both)
• Environment: Node.js v20.19.5 and v25.9.0
• Client: Python 3.11+ with requests library
• Operating System: macOS, Linux (Docker)
• Installation method: npx @stoplight/prism-cli@5.15.10

[rnagulapalle]

ran into this same class of problem recently. the root cause is in packages/http/src/mocker/index.ts — computeMockedHeaders iterates over every header from the spec and generates a value from the schema, including Content-Encoding. then assembleResponse merges those generated headers into the response without checking whether the header is something the mock server actually needs to back up with real behavior.

so when the spec says Content-Encoding can be gzip, the mocker dutifully picks one of the enum values, slaps it on the response, and sends an uncompressed body. every HTTP client that respects that header tries to decompress and dies.

this isn't just a Content-Encoding issue though — it's the same category for Content-Length (mocked body won't match the length from the schema), Transfer-Encoding (chunked not implemented), and arguably Content-Security-Policy or Strict-Transport-Security where the value from the spec describes the real server's behavior, not something a mock should echo. these are transport/security-level headers whose values need to be derived from the actual response, not generated from the spec schema.

simplest fix is probably a denylist in computeMockedHeaders that skips hop-by-hop and transport-derived headers. something like filtering out headers where name.toLowerCase() matches content-encoding, content-length, transfer-encoding, content-md5 before the generation loop runs.