What causes "Unable to ${codecName}-encode ${name}: ${t.getMessage()}" in jwtk/jjwt?

Inspect the exception cause to find the underlying write or codec failure.

jwtk/jjwt · error · io.jsonwebtoken.io.EncodingException

Unable to ${codecName}-encode ${name}: ${t.getMessage()}

Error message

Unable to ${codecName}-encode ${name}: ${t.getMessage()}

What it means

Thrown as an EncodingException when an encoding stream operation fails while encoding the named value with the configured codec. EncodingOutputStream catches any Throwable raised while writing/encoding and rewraps it, preserving the cause. The message names the codec and the logical name of what was being encoded.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/io/EncodingOutputStream.java:37

import io.jsonwebtoken.lang.Assert;

import java.io.OutputStream;

public class EncodingOutputStream extends FilteredOutputStream {

    private final String codecName;
    private final String name;

    public EncodingOutputStream(OutputStream out, String codecName, String name) {
        super(out);
        this.codecName = Assert.hasText(codecName, "codecName cannot be null or empty.");
        this.name = Assert.hasText(name, "name cannot be null or empty.");
    }

    @Override
    protected void onThrowable(Throwable t) {
        String msg = "Unable to " + this.codecName + "-encode " + this.name + ": " + t.getMessage();
        throw new EncodingException(msg, t);
    }
}

View on GitHub (pinned to fb71496164)

Solutions

Inspect the exception cause to find the underlying write or codec failure.
Verify the target OutputStream is open and writable for the duration of the encoding operation.
Check that the data being encoded is byte-encodable (no null byte arrays, no oversized payload).
If streaming to a servlet response or network socket, ensure it has not been committed/closed before encoding.

Example fix

// before
OutputStream out = response.getOutputStream(); // may already be committed/closed
new EncodingOutputStream(out, ...).write(data);
// after
if (!response.isCommitted()) {
    OutputStream out = response.getOutputStream();
    new EncodingOutputStream(out, ...).write(data);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Java
if (out == null) throw new IllegalArgumentException("OutputStream cannot be null");
if (data == null || data.length == 0) throw new IllegalArgumentException("nothing to encode");

Try / catch

try (OutputStream safeOut = ensureOpen(out)) {
    encoder.encodeTo(safeOut, data);
} catch (EncodingException e) {
    log.error("Failed to encode {}: {}", name, e.getMessage(), e.getCause());
    throw new IOException("Encoding failed", e);
}

Prevention

Use try-with-resources so output streams are properly managed and closed once.
Verify the target stream is not committed/closed before beginning encoding.
Keep payload sizes within transport limits (HTTP header ~8KB, etc.).
Check the cause of EncodingException to distinguish codec failures from IO failures.

When it happens

Trigger: Writing a JWT/JWS/JWE component through EncodingOutputStream when the underlying OutputStream throws an IOException (broken stream, disk full, closed pipe) or the codec rejects the byte content.

Common situations: Serializing a large claims payload to a stream backed by a closed socket or file; providing null/empty content that the codec rejects; container output stream already closed.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/28cffe3236d64638. Report an issue: GitHub.