Top Feign Pitfalls and How to Fix Them in Spring Cloud

1. Introduction

Feign is frequently used in microservice architectures to simplify inter‑service HTTP calls and provides built‑in load‑balancing via Ribbon. The following sections share real‑world problems encountered when using Feign and their solutions.

2. Common Feign Issues

2.1 400 Bad Request

When a Feign call includes a large number of menuIds as query parameters, the request may fail with a 400 error because the parameters are placed directly in the URL.

@PostMapping("/llsydn/getMenusByIdsAndTypes")
List<SysMenuDto> getMenusByIdsAndTypes(@RequestParam("menuIds") String menuIds,
                                      @RequestParam("menuType") String menuType);

Solution: change the method to accept a

@RequestBody

MultiValueMap

so the parameters are sent in the request body.

@PostMapping("/llsydn/getMenusByIdsAndTypes")
List<SysMenuDto> getMenusByIdsAndTypes(@RequestBody MultiValueMap<String,String> queryParam);

Calling code:

public List<SysMenuDto> getMenusByIdsAndNotType(String menuIds, String menuType) {
    MultiValueMap<String, String> valueMap = new LinkedMultiValueMap<>();
    valueMap.add("menuIds", menuIds);
    valueMap.add("menuType", menuType);
    return systemClient.getMenusByIdsAndTypes(valueMap);
}

2.2 Illegal Character Error

Enabling Feign compression can trigger an error like Illegal character ((CTRL-CHAR, code 31)) because only regular whitespace is allowed between tokens.

Solution: disable compression.

feign.compression.request.enabled=false
feign.compression.response.enabled=false

Alternatively, switch to OkHttp by adding the dependency:

<dependency>
  <groupId>io.github.openfeign</groupId>
  <artifactId>feign-okhttp</artifactId>
</dependency>

2.3 Chinese Garbled Characters

Chinese characters in request bodies may appear as question marks.

Solution: specify the charset in the @PostMapping annotation.

@PostMapping(value="/portal/core/appdata/install", consumes="application/json;charset=UTF-8")
void install(@RequestBody String data);

If the body is a JSON array string (e.g., [{},{}]), change the parameter type to an object array or List to avoid type‑mismatch errors.

@PostMapping(value="/portal/core/appdata/install", consumes="application/json;charset=UTF-8")
void install(@RequestBody Object[] data);

2.4 Too Many Body Parameters

Feign POST methods can contain only one @RequestBody. Adding multiple such annotations results in IllegalStateException: Method has too many Body parameters.

Solution: retain a single @RequestBody annotation and remove the others.

2.5 Read Timeout

Long‑running operations such as uploading an Excel file may cause Feign to time out.

Solution: configure timeout settings per Feign client.

@FeignClient(name="systemClient")
public interface SystemClient {
    @RequestMapping(path="/llsydn/importExcel", consumes={"multipart/form-data"})
    JsonResult importExcel(@RequestPart(name="file") MultipartFile file);
}

YAML configuration example:

feign:
  httpclient:
    enabled: true
  client:
    config:
      default:
        ConnectTimeOut: 10000
        ReadTimeOut: 10000
      systemClient:
        ConnectTimeOut: 30000
        ReadTimeOut: 30000

These tips should help you troubleshoot and resolve typical Feign problems encountered in real projects.