hutiefang76 · Oct 10, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,9 @@
   URL-encoded fields use the request's `CollectionFormat`. In multipart requests, numeric and
   boolean arrays create repeated parts, and `byte[]` values stay as one binary part. Multipart
   `char[]` values are still passed to the delegate encoder (#3607).
+* Values supplied through `@HeaderMap` are sent as literals instead of being parsed as URI template
+  expressions. This bypasses URI expression parsing entirely, including the URI expression length
+  limit, so a long literal value such as a large JSON payload reaches the wire unchanged.
 
 ### Version 13.16
 

diff --git a/core/src/main/java/feign/RequestTemplate.java b/core/src/main/java/feign/RequestTemplate.java
@@ -821,8 +821,12 @@ private RequestTemplate appendHeader(String name, Iterable<String> values, boole
       // a client can only produce content of one single type, so always override Content-Type and
       // only add a single type
       this.headers.remove(name);
+      List<String> contentTypes = Collections.singletonList(values.iterator().next());
       this.headers.put(
-          name, HeaderTemplate.create(name, Collections.singletonList(values.iterator().next())));
+          name,
+          literal
+              ? HeaderTemplate.literal(name, contentTypes)
+              : HeaderTemplate.create(name, contentTypes));
       return this;
     }
     this.headers.compute(

diff --git a/core/src/main/java/feign/RequestTemplateFactoryResolver.java b/core/src/main/java/feign/RequestTemplateFactoryResolver.java
@@ -171,7 +171,8 @@ private RequestTemplate addHeaderMapHeaders(
           values.add(currValue == null ? null : currValue.toString());
         }
 
-        mutable.header(currEntry.getKey(), values);
+        /* runtime @HeaderMap values are literals, not URI template expressions */
+        mutable.headerLiteral(currEntry.getKey(), values);
       }
       return mutable;
     }

diff --git a/core/src/test/java/feign/FeignTest.java b/core/src/test/java/feign/FeignTest.java
@@ -294,6 +294,77 @@ void headerMap() throws Exception {
             entry("Custom-Header", Arrays.asList("fooValue")));
   }
 
+  @Test
+  void headerMapWithJsonValueIsTreatedAsLiteral() throws Exception {
+    server.enqueue(new MockResponse());
+
+    TestInterface api = new TestInterfaceBuilder().target("http://localhost:" + server.getPort());
+
+    String json = "{\"test\":[\"123:861\"]}";
+    Map<String, Object> headerMap = new LinkedHashMap<>();
+    headerMap.put("Custom-Header", json);
+    api.headerMap(headerMap);
+
+    assertThat(server.takeRequest())
+        .hasHeaders(entry("Custom-Header", Collections.singletonList(json)));
+  }
+
+  @Test
+  void headerMapAcceptsLargeLiteralJson() throws Exception {
+    server.enqueue(new MockResponse());
+
+    TestInterface api = new TestInterfaceBuilder().target("http://localhost:" + server.getPort());
+
+    String value = "{\"payload\":\"" + "a".repeat(10001) + "\"}";
+    Map<String, Object> headerMap = new LinkedHashMap<>();
+    headerMap.put("Custom-Header", value);
+    api.headerMap(headerMap);
+
+    assertThat(server.takeRequest())
+        .hasHeaders(entry("Custom-Header", Collections.singletonList(value)));
+  }
+
+  @Test
+  void headerMapDoesNotStopAnnotatedHeaderExpansion() throws Exception {
+    server.enqueue(new MockResponse());
+
+    TestInterface api = new TestInterfaceBuilder().target("http://localhost:" + server.getPort());
+
+    api.supportComplexHttpHeaders("value");
+
+    assertThat(server.takeRequest())
+        .hasHeaders(entry("Custom", Collections.singletonList("value")));
+  }
+
+  @Test
+  void headerMapAcceptsLargeQuotedProfileMediaContentType() throws Exception {
+    server.enqueue(new MockResponse());
+
+    TestInterface api = new TestInterfaceBuilder().target("http://localhost:" + server.getPort());
+
+    String value = "application/json; note=\"{" + "a".repeat(10001) + "}\"";
+    Map<String, Object> headerMap = new LinkedHashMap<>();
+    headerMap.put("Content-Type", value);
+    api.headerMap(headerMap);
+
+    assertThat(server.takeRequest())
+        .hasHeaders(entry("Content-Type", Collections.singletonList(value)));
+  }
+
+  @Test
+  void headerMapContentTypeOnlyFirstValueSent() throws Exception {
+    server.enqueue(new MockResponse());
+
+    TestInterface api = new TestInterfaceBuilder().target("http://localhost:" + server.getPort());
+
+    Map<String, Object> headerMap = new LinkedHashMap<>();
+    headerMap.put("Content-Type", Arrays.asList("application/json", "text/plain"));
+    api.headerMap(headerMap);
+
+    assertThat(server.takeRequest())
+        .hasHeaders(entry("Content-Type", Collections.singletonList("application/json")));
+  }
+
   @Test
   void HeaderMapUserObject() throws Exception {
     server.enqueue(new MockResponse());