eclipse-vertx/vert.x · error · EncodeException

Failed to encode as JSON: ${e.getMessage()}

Error message

Failed to encode as JSON: ${e.getMessage()}

What it means

DatabindCodec.toString wraps any Jackson exception raised while serializing an object to a JSON string in io.vertx.core.encode.EncodeException. The library throws it whenever mapper.writeValueAsString (or the pretty-printer variant) fails, so callers get a uniform Vert.x exception type. The original Jackson message is appended after the prefix.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/json/jackson/DatabindCodec.java:169

    }
    if (type.getType() == Object.class) {
      value = (T) adapt(value);
    }
    return value;
  }

  @Override
  public String toString(Object object, boolean pretty) throws EncodeException {
    try {
      String result;
      if (pretty) {
        result = mapper.writerWithDefaultPrettyPrinter().writeValueAsString(object);
      } else {
        result = mapper.writeValueAsString(object);
      }
      return result;
    } catch (Exception e) {
      throw new EncodeException("Failed to encode as JSON: " + e.getMessage());
    }
  }

  @Override
  public Buffer toBuffer(Object object, boolean pretty) throws EncodeException {
    try {
      byte[] result;
      if (pretty) {
        result = mapper.writerWithDefaultPrettyPrinter().writeValueAsBytes(object);
      } else {
        result = mapper.writeValueAsBytes(object);
      }
      return Buffer.buffer(result);
    } catch (Exception e) {
      throw new EncodeException("Failed to encode as JSON: " + e.getMessage());
    }
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Read the wrapped Jackson cause message and fix the offending field/type (add getters, @JsonProperty, or make the class serializable)
2. Break cycles with @JsonIgnore or @JsonManagedReference/@JsonBackReference on the involved fields
3. Register a JsonSerializer via ObjectMapper customizer (DatabindCodec.mapper()) for the unsupported type
4. If encoding MapLike proxies (Hibernate), initialize/DTO-map entities before calling Json.encode

Example fix

// before
Json.encode(userEntity); // EncodeException: No serializer found for class User
// after
@JsonIgnore private LazyProxy proxy;
public String getName() { return name; }
Json.encode(userEntity);

public static boolean isJsonEncodable(Object o) {
  try { DatabindCodec.toBuffer(o); return true; }
  catch (EncodeException e) { return false; }
}

if (o instanceof JsonObject || o instanceof JsonArray || o instanceof String || o instanceof Number || o instanceof Boolean) { /* safely encodable */ }

try {
  String json = Json.encode(obj);
} catch (EncodeException e) {
  logger.warn("JSON encode failed: {}", e.getMessage());
  // fall back to a safe representation
}

When it happens

Trigger: Calling Json.encode / JsonObject.toString or DatabindCodec.toString(obj) with an object Jackson cannot serialize: no serializer found for a type (unmapped POJO, no getters), infinite recursion/cyclic reference, or an exception thrown inside a custom JsonSerializer.

Common situations: Encoding a plain Java object without a public getter or @JsonProperty; a POJO graph with a circular reference; putting non-JSON-serializable values (InputStream, Hibernate lazy proxies) into a JsonObject map; Vert.x upgrade where a custom codec no longer matches.

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

• Failed to encode as JSON:
• workerPoolSize must be > 0
• Expected an ISO 8601 formatted date time
• Failed to decode:${e.getMessage()}
• Failed to decode:

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/eb4141aaa68c6de4. Report an issue: GitHub.