fix(backend): prevent Content-Encoding mismatch in proxy responses

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

packages/backend/src/__tests__/proxy.test.ts

@@ -481,6 +481,50 @@ describe('proxy', () => {
  expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
  });
 
+ it('sets Accept-Encoding to identity to avoid double compression', async () => {
+ const mockResponse = new Response(JSON.stringify({ client: {} }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.headers.get('Accept-Encoding')).toBe('identity');
+ });
+
+ it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+ // Upstream may ignore Accept-Encoding: identity and compress anyway
+ const mockResponse = new Response('decoded body', {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/javascript',
+ 'Content-Encoding': 'gzip',
+ 'Content-Length': '500',
+ },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.headers.has('Content-Encoding')).toBe(false);
+ expect(response.headers.has('Content-Length')).toBe(false);
+ expect(response.headers.get('Content-Type')).toBe('application/javascript');
+ });
+
  it('preserves relative Location headers', async () => {
  const mockResponse = new Response(null, {
  status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
  'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  const fapiHost = new URL(fapiBaseUrl).host;
  headers.set('Host', fapiHost);
 
+ // Request uncompressed responses to avoid a double compression pass.
+ // fetch() auto-decompresses, so without this FAPI compresses → fetch
+ // decompresses → the serving layer re-compresses for the browser.
+ headers.set('Accept-Encoding', 'identity');
+
  // Set X-Forwarded-* headers for proxy awareness
  // Only set these if not already present (preserve values from upstream proxies)
  if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop headers
+ // Build response headers, excluding hop-by-hop and encoding headers
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
  responseHeaders.set(key, value);
  }
  });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  }
  }
 
-return new Response(response.body, {
+const proxyResponse = new Response(response.body, {
  status: response.status,
  statusText: response.statusText,
  headers: responseHeaders,
  });
+
+ // Some runtimes may re-add Content-Length when constructing the Response.
+ // Delete explicitly since fetch() decoded the body and the original values
+ // no longer reflect the actual content.
+ for (const header of RESPONSE_HEADERS_TO_STRIP) {
+ proxyResponse.headers.delete(header);
+ }
+
+ return proxyResponse;
  } catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

packages/backend/src/__tests__/proxy.test.ts

@@ -481,6 +481,50 @@ describe('proxy', () => {
  expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
  });
 
+ it('sets Accept-Encoding to identity to avoid double compression', async () => {
+ const mockResponse = new Response(JSON.stringify({ client: {} }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.headers.get('Accept-Encoding')).toBe('identity');
+ });
+
+ it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+ // Upstream may ignore Accept-Encoding: identity and compress anyway
+ const mockResponse = new Response('decoded body', {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/javascript',
+ 'Content-Encoding': 'gzip',
+ 'Content-Length': '500',
+ },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.headers.has('Content-Encoding')).toBe(false);
+ expect(response.headers.has('Content-Length')).toBe(false);
+ expect(response.headers.get('Content-Type')).toBe('application/javascript');
+ });
+
  it('preserves relative Location headers', async () => {
  const mockResponse = new Response(null, {
  status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
  'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  const fapiHost = new URL(fapiBaseUrl).host;
  headers.set('Host', fapiHost);
 
+ // Request uncompressed responses to avoid a double compression pass.
+ // fetch() auto-decompresses, so without this FAPI compresses → fetch
+ // decompresses → the serving layer re-compresses for the browser.
+ headers.set('Accept-Encoding', 'identity');
+
  // Set X-Forwarded-* headers for proxy awareness
  // Only set these if not already present (preserve values from upstream proxies)
  if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop headers
+ // Build response headers, excluding hop-by-hop and encoding headers
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
  responseHeaders.set(key, value);
  }
  });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  }
  }
 
-return new Response(response.body, {
+const proxyResponse = new Response(response.body, {
  status: response.status,
  statusText: response.statusText,
  headers: responseHeaders,
  });
+
+ // Some runtimes may re-add Content-Length when constructing the Response.
+ // Delete explicitly since fetch() decoded the body and the original values
+ // no longer reflect the actual content.
+ for (const header of RESPONSE_HEADERS_TO_STRIP) {
+ proxyResponse.headers.delete(header);
+ }
+
+ return proxyResponse;
  } catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

packages/backend/src/__tests__/proxy.test.ts

@@ -481,6 +481,50 @@ describe('proxy', () => {
  expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
  });
 
+ it('sets Accept-Encoding to identity to avoid double compression', async () => {
+ const mockResponse = new Response(JSON.stringify({ client: {} }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.headers.get('Accept-Encoding')).toBe('identity');
+ });
+
+ it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+ // Upstream may ignore Accept-Encoding: identity and compress anyway
+ const mockResponse = new Response('decoded body', {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/javascript',
+ 'Content-Encoding': 'gzip',
+ 'Content-Length': '500',
+ },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.headers.has('Content-Encoding')).toBe(false);
+ expect(response.headers.has('Content-Length')).toBe(false);
+ expect(response.headers.get('Content-Type')).toBe('application/javascript');
+ });
+
  it('preserves relative Location headers', async () => {
  const mockResponse = new Response(null, {
  status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
  'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  const fapiHost = new URL(fapiBaseUrl).host;
  headers.set('Host', fapiHost);
 
+ // Request uncompressed responses to avoid a double compression pass.
+ // fetch() auto-decompresses, so without this FAPI compresses → fetch
+ // decompresses → the serving layer re-compresses for the browser.
+ headers.set('Accept-Encoding', 'identity');
+
  // Set X-Forwarded-* headers for proxy awareness
  // Only set these if not already present (preserve values from upstream proxies)
  if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop headers
+ // Build response headers, excluding hop-by-hop and encoding headers
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
  responseHeaders.set(key, value);
  }
  });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  }
  }
 
-return new Response(response.body, {
+const proxyResponse = new Response(response.body, {
  status: response.status,
  statusText: response.statusText,
  headers: responseHeaders,
  });
+
+ // Some runtimes may re-add Content-Length when constructing the Response.
+ // Delete explicitly since fetch() decoded the body and the original values
+ // no longer reflect the actual content.
+ for (const header of RESPONSE_HEADERS_TO_STRIP) {
+ proxyResponse.headers.delete(header);
+ }
+
+ return proxyResponse;
  } catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

packages/backend/src/__tests__/proxy.test.ts

@@ -481,6 +481,50 @@ describe('proxy', () => {
  expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
  });
 
+ it('sets Accept-Encoding to identity to avoid double compression', async () => {
+ const mockResponse = new Response(JSON.stringify({ client: {} }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.headers.get('Accept-Encoding')).toBe('identity');
+ });
+
+ it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+ // Upstream may ignore Accept-Encoding: identity and compress anyway
+ const mockResponse = new Response('decoded body', {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/javascript',
+ 'Content-Encoding': 'gzip',
+ 'Content-Length': '500',
+ },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.headers.has('Content-Encoding')).toBe(false);
+ expect(response.headers.has('Content-Length')).toBe(false);
+ expect(response.headers.get('Content-Type')).toBe('application/javascript');
+ });
+
  it('preserves relative Location headers', async () => {
  const mockResponse = new Response(null, {
  status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
  'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  const fapiHost = new URL(fapiBaseUrl).host;
  headers.set('Host', fapiHost);
 
+ // Request uncompressed responses to avoid a double compression pass.
+ // fetch() auto-decompresses, so without this FAPI compresses → fetch
+ // decompresses → the serving layer re-compresses for the browser.
+ headers.set('Accept-Encoding', 'identity');
+
  // Set X-Forwarded-* headers for proxy awareness
  // Only set these if not already present (preserve values from upstream proxies)
  if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop headers
+ // Build response headers, excluding hop-by-hop and encoding headers
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
  responseHeaders.set(key, value);
  }
  });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  }
  }
 
-return new Response(response.body, {
+const proxyResponse = new Response(response.body, {
  status: response.status,
  statusText: response.statusText,
  headers: responseHeaders,
  });
+
+ // Some runtimes may re-add Content-Length when constructing the Response.
+ // Delete explicitly since fetch() decoded the body and the original values
+ // no longer reflect the actual content.
+ for (const header of RESPONSE_HEADERS_TO_STRIP) {
+ proxyResponse.headers.delete(header);
+ }
+
+ return proxyResponse;
  } catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

packages/backend/src/__tests__/proxy.test.ts

@@ -481,6 +481,50 @@ describe('proxy', () => {
  expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
  });
 
+ it('sets Accept-Encoding to identity to avoid double compression', async () => {
+ const mockResponse = new Response(JSON.stringify({ client: {} }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.headers.get('Accept-Encoding')).toBe('identity');
+ });
+
+ it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+ // Upstream may ignore Accept-Encoding: identity and compress anyway
+ const mockResponse = new Response('decoded body', {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/javascript',
+ 'Content-Encoding': 'gzip',
+ 'Content-Length': '500',
+ },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.headers.has('Content-Encoding')).toBe(false);
+ expect(response.headers.has('Content-Length')).toBe(false);
+ expect(response.headers.get('Content-Type')).toBe('application/javascript');
+ });
+
  it('preserves relative Location headers', async () => {
  const mockResponse = new Response(null, {
  status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
  'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  const fapiHost = new URL(fapiBaseUrl).host;
  headers.set('Host', fapiHost);
 
+ // Request uncompressed responses to avoid a double compression pass.
+ // fetch() auto-decompresses, so without this FAPI compresses → fetch
+ // decompresses → the serving layer re-compresses for the browser.
+ headers.set('Accept-Encoding', 'identity');
+
  // Set X-Forwarded-* headers for proxy awareness
  // Only set these if not already present (preserve values from upstream proxies)
  if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop headers
+ // Build response headers, excluding hop-by-hop and encoding headers
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
  responseHeaders.set(key, value);
  }
  });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  }
  }
 
-return new Response(response.body, {
+const proxyResponse = new Response(response.body, {
  status: response.status,
  statusText: response.statusText,
  headers: responseHeaders,
  });
+
+ // Some runtimes may re-add Content-Length when constructing the Response.
+ // Delete explicitly since fetch() decoded the body and the original values
+ // no longer reflect the actual content.
+ for (const header of RESPONSE_HEADERS_TO_STRIP) {
+ proxyResponse.headers.delete(header);
+ }
+
+ return proxyResponse;
  } catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

packages/backend/src/__tests__/proxy.test.ts

@@ -481,6 +481,50 @@ describe('proxy', () => {
  expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
  });
 
+ it('sets Accept-Encoding to identity to avoid double compression', async () => {
+ const mockResponse = new Response(JSON.stringify({ client: {} }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.headers.get('Accept-Encoding')).toBe('identity');
+ });
+
+ it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+ // Upstream may ignore Accept-Encoding: identity and compress anyway
+ const mockResponse = new Response('decoded body', {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/javascript',
+ 'Content-Encoding': 'gzip',
+ 'Content-Length': '500',
+ },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.headers.has('Content-Encoding')).toBe(false);
+ expect(response.headers.has('Content-Length')).toBe(false);
+ expect(response.headers.get('Content-Type')).toBe('application/javascript');
+ });
+
  it('preserves relative Location headers', async () => {
  const mockResponse = new Response(null, {
  status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
  'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  const fapiHost = new URL(fapiBaseUrl).host;
  headers.set('Host', fapiHost);
 
+ // Request uncompressed responses to avoid a double compression pass.
+ // fetch() auto-decompresses, so without this FAPI compresses → fetch
+ // decompresses → the serving layer re-compresses for the browser.
+ headers.set('Accept-Encoding', 'identity');
+
  // Set X-Forwarded-* headers for proxy awareness
  // Only set these if not already present (preserve values from upstream proxies)
  if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop headers
+ // Build response headers, excluding hop-by-hop and encoding headers
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
  responseHeaders.set(key, value);
  }
  });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  }
  }
 
-return new Response(response.body, {
+const proxyResponse = new Response(response.body, {
  status: response.status,
  statusText: response.statusText,
  headers: responseHeaders,
  });
+
+ // Some runtimes may re-add Content-Length when constructing the Response.
+ // Delete explicitly since fetch() decoded the body and the original values
+ // no longer reflect the actual content.
+ for (const header of RESPONSE_HEADERS_TO_STRIP) {
+ proxyResponse.headers.delete(header);
+ }
+
+ return proxyResponse;
  } catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

packages/backend/src/__tests__/proxy.test.ts

@@ -481,6 +481,50 @@ describe('proxy', () => {
  expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
  });
 
+ it('sets Accept-Encoding to identity to avoid double compression', async () => {
+ const mockResponse = new Response(JSON.stringify({ client: {} }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.headers.get('Accept-Encoding')).toBe('identity');
+ });
+
+ it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+ // Upstream may ignore Accept-Encoding: identity and compress anyway
+ const mockResponse = new Response('decoded body', {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/javascript',
+ 'Content-Encoding': 'gzip',
+ 'Content-Length': '500',
+ },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.headers.has('Content-Encoding')).toBe(false);
+ expect(response.headers.has('Content-Length')).toBe(false);
+ expect(response.headers.get('Content-Type')).toBe('application/javascript');
+ });
+
  it('preserves relative Location headers', async () => {
  const mockResponse = new Response(null, {
  status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
  'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  const fapiHost = new URL(fapiBaseUrl).host;
  headers.set('Host', fapiHost);
 
+ // Request uncompressed responses to avoid a double compression pass.
+ // fetch() auto-decompresses, so without this FAPI compresses → fetch
+ // decompresses → the serving layer re-compresses for the browser.
+ headers.set('Accept-Encoding', 'identity');
+
  // Set X-Forwarded-* headers for proxy awareness
  // Only set these if not already present (preserve values from upstream proxies)
  if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop headers
+ // Build response headers, excluding hop-by-hop and encoding headers
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
  responseHeaders.set(key, value);
  }
  });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  }
  }
 
-return new Response(response.body, {
+const proxyResponse = new Response(response.body, {
  status: response.status,
  statusText: response.statusText,
  headers: responseHeaders,
  });
+
+ // Some runtimes may re-add Content-Length when constructing the Response.
+ // Delete explicitly since fetch() decoded the body and the original values
+ // no longer reflect the actual content.
+ for (const header of RESPONSE_HEADERS_TO_STRIP) {
+ proxyResponse.headers.delete(header);
+ }
+
+ return proxyResponse;
  } catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

packages/backend/src/__tests__/proxy.test.ts

@@ -481,6 +481,50 @@ describe('proxy', () => {
  expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
  });
 
+ it('sets Accept-Encoding to identity to avoid double compression', async () => {
+ const mockResponse = new Response(JSON.stringify({ client: {} }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.headers.get('Accept-Encoding')).toBe('identity');
+ });
+
+ it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+ // Upstream may ignore Accept-Encoding: identity and compress anyway
+ const mockResponse = new Response('decoded body', {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/javascript',
+ 'Content-Encoding': 'gzip',
+ 'Content-Length': '500',
+ },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.headers.has('Content-Encoding')).toBe(false);
+ expect(response.headers.has('Content-Length')).toBe(false);
+ expect(response.headers.get('Content-Type')).toBe('application/javascript');
+ });
+
  it('preserves relative Location headers', async () => {
  const mockResponse = new Response(null, {
  status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
  'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  const fapiHost = new URL(fapiBaseUrl).host;
  headers.set('Host', fapiHost);
 
+ // Request uncompressed responses to avoid a double compression pass.
+ // fetch() auto-decompresses, so without this FAPI compresses → fetch
+ // decompresses → the serving layer re-compresses for the browser.
+ headers.set('Accept-Encoding', 'identity');
+
  // Set X-Forwarded-* headers for proxy awareness
  // Only set these if not already present (preserve values from upstream proxies)
  if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop headers
+ // Build response headers, excluding hop-by-hop and encoding headers
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
  responseHeaders.set(key, value);
  }
  });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  }
  }
 
-return new Response(response.body, {
+const proxyResponse = new Response(response.body, {
  status: response.status,
  statusText: response.statusText,
  headers: responseHeaders,
  });
+
+ // Some runtimes may re-add Content-Length when constructing the Response.
+ // Delete explicitly since fetch() decoded the body and the original values
+ // no longer reflect the actual content.
+ for (const header of RESPONSE_HEADERS_TO_STRIP) {
+ proxyResponse.headers.delete(header);
+ }
+
+ return proxyResponse;
  } catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);