eclipse-vertx/vert.x · error · IllegalStateException

Already a codec registered with name

Error message

Already a codec registered with name

What it means

Event Bus message codecs must have unique names. CodecManager.registerCodec throws this IllegalStateException when a user codec with the same name() is already in the user codec map, preventing silent replacement of an existing codec. Register each codec name only once per Vertx instance.

Source

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

        }
      }
    }
    if (codec == null) {
      throw new IllegalArgumentException("No message codec for type: " + body.getClass());
    }
    return codec;
  }

  public MessageCodec getCodec(String codecName) {
    return userCodecMap.get(codecName);
  }

  public void registerCodec(MessageCodec codec) {
    Objects.requireNonNull(codec, "codec");
    Objects.requireNonNull(codec.name(), "code.name()");
    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())) {

View on GitHub (pinned to fb308bd8c3)

Solutions

  1. Check if the codec name is already registered before calling registerCodec, or wrap the call in a guard using eventBus.codecResolver(codec.name()) != null style check / try-catch.
  2. Register codecs only once per Vertx instance, e.g. in a shared bootstrap outside verticle deployment.
  3. Use a unique codec name (namespaced like 'com.myapp.MyCodec') to avoid collisions with third-party codecs.
  4. Create a new Vertx instance for isolated deployments/tests instead of reusing one.

Example fix

// before
bus.registerCodec(new MyCodec()); // throws on redeploy
// after
if (bus.codecResolver("mycodec") == null) {
  bus.registerCodec(new MyCodec());
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (bus.codecResolver(myCodec.name()) == null) {
  bus.registerCodec(myCodec);
}

Try / catch

try {
  bus.registerCodec(codec);
} catch (IllegalStateException e) {
  // codec name already registered; treat as idempotent no-op
}

Prevention

When it happens

Trigger: Calling vertx.eventBus().registerCodec(codec) when a codec whose name() equals codec.name() was previously registered, or registering the same codec instance twice.

Common situations: Re-deploying a verticle that registers codecs in its start() method against a shared Vertx; two libraries both registering a codec named 'mycodec'; test suites re-registering codecs per test without a fresh Vertx.

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/8705f532dfd327c5. Report an issue: GitHub.