eclipse-vertx/vert.x · error · IllegalStateException

Already a default codec registered for class

Error message

Already a default codec registered for class

What it means

EventBus.registerDefaultCodec binds a Java class to a MessageCodec; only one default codec is allowed per class. This IllegalStateException is thrown when defaultCodecMap already contains an entry for the given class, so Vert.x refuses to silently overwrite the existing mapping.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/eventbus/impl/CodecManager.java:149

    checkSystemCodec(codec);
    if (userCodecMap.containsKey(codec.name())) {
      throw new IllegalStateException("Already a codec registered with name " + codec.name());
    }
    userCodecMap.put(codec.name(), codec);
  }

  public void unregisterCodec(String name) {
    Objects.requireNonNull(name);
    userCodecMap.remove(name);
  }

  public <T> void registerDefaultCodec(Class<T> clazz, MessageCodec<T, ?> codec) {
    Objects.requireNonNull(clazz);
    Objects.requireNonNull(codec, "codec");
    Objects.requireNonNull(codec.name(), "code.name()");
    checkSystemCodec(codec);
    if (defaultCodecMap.containsKey(clazz)) {
      throw new IllegalStateException("Already a default codec registered for class " + clazz);
    }
    if (userCodecMap.containsKey(codec.name())) {
      throw new IllegalStateException("Already a codec registered with name " + codec.name());
    }
    defaultCodecMap.put(clazz, codec);
    userCodecMap.put(codec.name(), codec);
  }

  public void unregisterDefaultCodec(Class clazz) {
    Objects.requireNonNull(clazz);
    MessageCodec codec = defaultCodecMap.remove(clazz);
    if (codec != null) {
      userCodecMap.remove(codec.name());
    }
  }

  public MessageCodec[] systemCodecs() {
    return systemCodecs;

View on GitHub (pinned to fb308bd8c3)

Solutions

  1. Guard with a try-catch or check whether a codec is already registered for the class before registering.
  2. Move default codec registration to a single, idempotent bootstrap step executed once per Vertx instance.
  3. Register the default codec before deploying any verticles, and only in the verticle that owns the type.
  4. Use unregisterDefaultCodec(clazz) before re-registering if replacement is intentional (and acceptable).

Example fix

// before
verticles.forEach(v -> v.registerCodecs(bus)); // double registration
// after
AtomicBoolean registered = new AtomicBoolean();
if (registered.compareAndSet(false, true)) {
  bus.registerDefaultCodec(MyMsg.class, new MyMsgCodec());
}
Defensive patterns

Strategy: validation

Validate before calling

// wrap registration in an idempotent guard
private static final Set<Class<?>> REGISTERED = ConcurrentHashMap.newKeySet();
if (REGISTERED.add(MyMsg.class)) {
  bus.registerDefaultCodec(MyMsg.class, new MyMsgCodec());
}

Try / catch

try {
  bus.registerDefaultCodec(MyMsg.class, codec);
} catch (IllegalStateException e) {
  // already mapped; ignore
}

Prevention

When it happens

Trigger: Calling eventBus().registerDefaultCodec(MyClass.class, codec) after MyClass.class was already mapped (by the same or another codec), e.g. during verticle redeploy or double initialization.

Common situations: Two verticles each registering a default codec for the same class; framework bootstrap code running more than once; tests that don't close the previous Vertx before starting a new registration round on a shared bus.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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