eclipse-vertx/vert.x · error · EncodeException

Mapping

Error message

Mapping 

What it means

JacksonCodec.encodeJson encodes Vert.x JSON values (Map/List/String/Number/Boolean/null) to a Jackson generator without databind. When the value's type is not one of the supported single types (encodeSingleType returns false), it throws EncodeException naming the class, stating that mapping is unavailable without Jackson Databind on the classpath. The 'Mapping ' prefix is concatenated with the class name of the unsupported object.

Source

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

      } else if (json instanceof JsonArray) {
        json = ((JsonArray)json).getList();
      }
      if (json instanceof Map) {
        generator.writeStartObject();
        for (Map.Entry<String, ?> e : ((Map<String, ?>)json).entrySet()) {
          generator.writeName(e.getKey());
          Object value = e.getValue();
          encodeJson0(value, generator);
        }
        generator.writeEndObject();
      } else if (json instanceof List) {
        generator.writeStartArray();
        for (Object item : (List<?>) json) {
          encodeJson0(item, generator);
        }
        generator.writeEndArray();
      } else if (!encodeSingleType(generator, json)) {
        throw new EncodeException("Mapping " + json.getClass().getName() + "  is not available without Jackson Databind on the classpath");
      }
    } catch (IOException e) {
      throw new EncodeException(e.getMessage(), e);
    }
  }

  /**
   * This is a way to overcome a limit of OpenJDK on MaxRecursiveInlineLevel:
   * avoiding the "direct" recursive calls allow the JIT to have a better inlining budget for the recursive calls.
   */
  private static void encodeJson0(Object json, JsonGenerator generator) throws EncodeException {
    try {
      if (json instanceof JsonObject) {
        json = ((JsonObject)json).getMap();
      } else if (json instanceof JsonArray) {
        json = ((JsonArray)json).getList();
      }
      if (json instanceof Map) {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Add com.fasterxml.jackson.core:jackson-databind to the classpath so POJO/extra types can be serialized
2. Convert unsupported types manually before encoding: pass JsonObject.getMap()/the underlying Map, call toString(), or pre-encode to supported JSON types
3. Encode Buffer/Instant as base64 Strings or ISO strings yourself before calling encodeJson

Example fix

// before
JacksonCodec.encodeJson(generator, myPojo); // EncodeException: Mapping com.acme.Pojo is not available...
// after
JacksonCodec.encodeJson(generator, Json.encodeToBuffer(myPojo).toJsonObject().getMap());
// or: add jackson-databind to the classpath

static boolean isEncodableWithoutDatabind(Object v) {
  return v == null || v instanceof Map || v instanceof List || v instanceof String
      || v instanceof Number || v instanceof Boolean;
}

static boolean canEncode(Object v) {
  return !(v instanceof JsonObject) && isEncodableWithoutDatabind(v);
}

try {
  JacksonCodec.encodeJson(generator, value);
} catch (EncodeException e) {
  if (e.getMessage().contains("without Jackson Databind")) {
    // add jackson-databind or convert value to supported types
  }
}

When it happens

Trigger: Calling JacksonCodec.encodeJson(generator, value) with a POJO, a JsonObject, a byte[], an Instant, or any type that is not Map/List/String/Number/Boolean/null while Jackson's databind module (jackson-databind) is not on the classpath, so no fallback POJO serialization exists.

Common situations: Running with only jackson-core on the classpath (databind excluded to reduce size or excluded by the v3 jackson module packaging) and trying to encode arbitrary POJOs; passing a JsonObject rather than its underlying map; encoding Buffer/Instant directly.

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

• ${e.getMessage()}
• Failed to encode as JSON:
• Expected an ISO 8601 formatted date time
• Unexpected trailing token
• Expecting the current parser token to be the start of an obj

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