OpenFeign/feign · error · IllegalStateException

Error occurred during encoding of the uri:

Error message

Error occurred during encoding of the uri:

What it means

UriUtils wraps any IOException thrown while percent-encoding a URI chunk into an IllegalStateException. Encoding writes to an in-memory ByteArrayOutputStream, so an IOException here is unexpected and signals an internal encoding failure rather than bad user input.

Solutions

  1. Inspect the wrapped IOException (getCause) for the root cause
  2. Verify the template/URI input and charset are valid
  3. Upgrade Feign; if reproducible, file an issue with the input URI and charset
Defensive patterns

Strategy: try-catch

Try / catch

try {
  encoded = UriUtils.encode(value, charset);
} catch (IllegalStateException e) {
  logger.error("URI encoding failed: {}", e.getCause());
}

Prevention

When it happens

Trigger: IOException thrown inside the encodeInternal loop (e.g. during charset operations or the internal byte stream) while calling UriUtils.encode/encodeChunk.

Common situations: Extremely rare in practice since ByteArrayOutputStream rarely throws; can surface from charset encoder issues or wrapped streams in modified/custom builds.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of OpenFeign/feign@e2a1e27560 (2026-09-10). Data as JSON: /api/errors/210cd02f158e14f5. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/feign/template/UriUtils.java:168

  private static String encodeChunk(String value, Charset charset, boolean allowReserved) {
    if (isEncoded(value, charset)) {
      return value;
    }

    byte[] data = value.getBytes(charset);
    try (ByteArrayOutputStream bos = new ByteArrayOutputStream()) {
      for (byte b : data) {
        if (isUnreserved((char) b)) {
          bos.write(b);
        } else if (isReserved((char) b) && allowReserved) {
          bos.write(b);
        } else {
          pctEncode(b, bos);
        }
      }
      return new String(bos.toByteArray(), charset);
    } catch (IOException ioe) {
      throw new IllegalStateException(
          "Error occurred during encoding of the uri: " + ioe.getMessage(), ioe);
    }
  }

  /**
   * Percent Encode the provided byte.
   *
   * @param data to encode
   * @param bos with the output stream to use.
   */
  private static void pctEncode(byte data, ByteArrayOutputStream bos) {
    bos.write('%');
    char hex1 = Character.toUpperCase(Character.forDigit((data >> 4) & 0xF, 16));
    char hex2 = Character.toUpperCase(Character.forDigit(data & 0xF, 16));
    bos.write(hex1);
    bos.write(hex2);
  }

View on GitHub (pinned to e2a1e27560)