eclipse-vertx/vert.x · error · EncodeException

Failed to encode as JSON:

Error message

Failed to encode as JSON: 

What it means

DatabindCodec.toString serializes an object with the Jackson ObjectMapper (optionally pretty-printed). Any exception during serialization — unserializable types, self-referencing structures, failing getters — is rethrown as Vert.x EncodeException with message 'Failed to encode as JSON: ' plus the cause message.

Source

Thrown at vertx-core/src/main/java21/io/vertx/core/json/jackson/v3/DatabindCodec.java:148

    }
    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 cause message to find the failing property; annotate it with @JsonIgnore or remove it from the DTO.
2. Break circular references (drop the back-reference or use @JsonManagedReference/@JsonBackReference).
3. Add public getters or Jackson annotations (@JsonProperty) so the bean is serializable.
4. Register a module/serializer for the unsupported type, or convert it to a Map/POJO before encoding.

Example fix

// before
class Node { Node parent; Node child; } // infinite recursion
// after
class Node { @JsonIgnore Node parent; Node child; }

static boolean isJsonSafe(Object o) {
  try { Json.encode(o); return true; } catch (EncodeException e) { return false; }
}

boolean serializable(Object o) {
  return !(o instanceof Throwable || o instanceof InputStream || o instanceof Logger);
}

try {
  String json = Json.encode(dto);
} catch (EncodeException e) {
  log.error("Cannot serialize {}: {}", dto.getClass(), e.getMessage());
}

When it happens

Trigger: Json.encode(obj) / toString(obj) where obj contains types Jackson cannot serialize: no public getters, infinite recursion between objects, unhandled types like Throwable or InputStream in fields.

Common situations: Passing domain objects with circular references (parent<->child) to Json.encode; POJOs without getters; embedding non-serializable library objects (e.g. Vert.x future, exceptions) in a response DTO.

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: ${e.getMessage()}
• 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/0f2e647236ee4bfe. Report an issue: GitHub.