{"record":{"id":"31cf55bcd17da2d9","repo":"eclipse-vertx/vert.x","slug":"highwatermark","errorCode":null,"errorMessage":"highWaterMark ","messagePattern":"highWaterMark ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/streams/impl/InboundBuffer.java","lineNumber":92,"sourceCode":"  private final long highWaterMark;\n  private long demand;\n  private Handler<E> handler;\n  private boolean overflow;\n  private Handler<Void> drainHandler;\n  private Handler<Void> emptyHandler;\n  private Handler<Throwable> exceptionHandler;\n  private boolean emitting;\n\n  public InboundBuffer(Context context) {\n    this(context, 16L);\n  }\n\n  public InboundBuffer(Context context, long highWaterMark) {\n    if (context == null) {\n      throw new NullPointerException(\"context must not be null\");\n    }\n    if (highWaterMark < 0) {\n      throw new IllegalArgumentException(\"highWaterMark \" + highWaterMark + \" >= 0\");\n    }\n    this.context = (ContextInternal) context;\n    this.highWaterMark = highWaterMark;\n    this.demand = Long.MAX_VALUE;\n    // empty ArrayDeque's constructor ArrayDeque allocates 16 elements; let's delay the allocation to be of the proper size\n    this.pending = null;\n  }\n\n  private void checkThread() {\n    if (!context.inThread()) {\n      throw new IllegalStateException(\"This operation must be called from a Vert.x thread\");\n    }\n  }\n\n  /**\n   * Write an {@code element} to the buffer. The element will be delivered synchronously to the handler when\n   * it is possible, otherwise it will be queued for later delivery.\n   *","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/streams/impl/InboundBuffer.java#L74-L110","documentation":"InboundBuffer's constructor validates that the high-water mark used for back-pressure is non-negative. Passing a negative value throws IllegalArgumentException with the configured value, because a negative threshold makes the writable/overflow semantics of the buffer meaningless.","triggerScenarios":"new InboundBuffer(context, highWaterMark) with a negative long, e.g. setHighWaterMark(-1) in ReadStream options or a computed value from a misparsed config (size = -1 meaning 'unlimited' by some external convention).","commonSituations":"Using -1 as a sentinel for 'no limit' copied from another library; config values parsed with a default of -1; arithmetic underflow when computing buffer sizes.","solutions":["Pass a positive (or zero) highWaterMark; use Long.MAX_VALUE if unbounded delivery is intended","Clamp the configured value before constructing: Math.max(0, configuredValue)","Fix the config source that supplies the -1 sentinel and parse it into a valid positive value"],"exampleFix":"// before\nlong hwm = config.getBufferLimit(); // may be -1\nInboundBuffer buf = new InboundBuffer(context, hwm);\n// after\nlong hwm = config.getBufferLimit();\nInboundBuffer buf = new InboundBuffer(context, hwm < 0 ? Long.MAX_VALUE : hwm);","handlingStrategy":"validation","validationCode":"long hwm = configuredHighWaterMark;\nif (hwm < 0) hwm = Long.MAX_VALUE; // unbounded\nnew InboundBuffer(context, hwm);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat -1 sentinels explicitly before constructing","Clamp config-driven sizes with Math.max(0, value)","Document that highWaterMark must be >= 0"],"tags":["streams","backpressure","configuration","validation"],"backgroundTag":"value-out-of-range","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}