{"record":{"id":"3c0bd8afe0a58eac","repo":"eclipse-vertx/vert.x","slug":"can-t-register-a-system-codec","errorCode":null,"errorMessage":"Can't register a system codec","messagePattern":"Can't register a system codec","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/eventbus/impl/CodecManager.java","lineNumber":172,"sourceCode":"    defaultCodecMap.put(clazz, codec);\n    userCodecMap.put(codec.name(), codec);\n  }\n\n  public void unregisterDefaultCodec(Class clazz) {\n    Objects.requireNonNull(clazz);\n    MessageCodec codec = defaultCodecMap.remove(clazz);\n    if (codec != null) {\n      userCodecMap.remove(codec.name());\n    }\n  }\n\n  public MessageCodec[] systemCodecs() {\n    return systemCodecs;\n  }\n\n  private void checkSystemCodec(MessageCodec codec) {\n    if (codec.systemCodecID() != -1) {\n      throw new IllegalArgumentException(\"Can't register a system codec\");\n    }\n  }\n\n  private MessageCodec[] codecs(MessageCodec... codecs) {\n    MessageCodec[] arr = new MessageCodec[codecs.length];\n    for (MessageCodec codec : codecs) {\n      arr[codec.systemCodecID()] = codec;\n    }\n    return arr;\n  }\n\n  public void clusterSerializableCheck(Function<String, Boolean> classNamePredicate) {\n    this.clusterSerializableCheck = Objects.requireNonNull(classNamePredicate);\n  }\n\n  public boolean acceptClusterSerializable(String className) {\n    return clusterSerializableCheck.apply(className);\n  }","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/eventbus/impl/CodecManager.java#L154-L190","documentation":"Vert.x ships built-in system codecs (null, ping, pong, reply failures, ClusterSerializable, Serializable, etc.) identified by systemCodecID() != -1. CodecManager.checkSystemCodec throws this IllegalArgumentException to forbid user registration of any codec claiming a system codec ID, protecting the internal codec table from corruption.","triggerScenarios":"Implementing a custom MessageCodec whose systemCodecID() returns 0 or another non -1 value, then calling registerCodec or registerDefaultCodec with it.","commonSituations":"Copying the source of a built-in codec (e.g. NullMessageCodec) as a template and forgetting to override systemCodecID() to return -1; implementing the MessageCodec interface by delegating to a system codec.","solutions":["Override systemCodecID() in your custom codec to return -1.","If you need a system codec's behavior, wrap it in your own codec class with systemCodecID() = -1 rather than registering the system codec itself.","Register the message type with a normal user codec name instead of attempting to reuse built-in codec IDs."],"exampleFix":"// before\n@Override public int systemCodecID() { return 0; } // reserved for system codecs\n// after\n@Override public int systemCodecID() { return -1; }","handlingStrategy":"validation","validationCode":"if (codec.systemCodecID() != -1) {\n  throw new IllegalArgumentException(\"custom codec must return -1 from systemCodecID()\");\n}\nbus.registerCodec(codec);","typeGuard":null,"tryCatchPattern":"try {\n  bus.registerCodec(codec);\n} catch (IllegalArgumentException e) {\n  // system codec rejected; fix systemCodecID()\n}","preventionTips":["Always override systemCodecID() to return -1 in custom MessageCodecs","Never copy built-in codec sources without changing the system codec ID","Add a unit test asserting your codecs' systemCodecID() == -1"],"tags":["eventbus","codec","illegal-argument","system-codec"],"backgroundTag":"invalid-argument-value","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}