{"record":{"id":"4cac8dbe21456ec0","repo":"aeron-io/aeron","slug":"name-value-cannot-be-negative-value","errorCode":null,"errorMessage":"`${name}` value cannot be negative: ${value}","messagePattern":"`(.+?)` value cannot be negative: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":2553,"sourceCode":"        if (null != valueNs)\n        {\n            sb.append(paramName).append('=').append(SystemUtil.formatDuration(valueNs)).append('|');\n        }\n    }\n\n    private static void appendSize(final StringBuilder sb, final String paramName, final Integer value)\n    {\n        if (null != value)\n        {\n            sb.append(paramName).append('=').append(SystemUtil.formatSize(value)).append('|');\n        }\n    }\n\n    private static Long requireNonNegative(final Long value, final String name)\n    {\n        if (null != value && value < 0)\n        {\n            throw new IllegalArgumentException(\"`\" + name + \"` value cannot be negative: \" + value);\n        }\n        return value;\n    }\n\n    private static Integer requireNonNegative(final Integer value, final String name)\n    {\n        if (null != value && value < 0)\n        {\n            throw new IllegalArgumentException(\"`\" + name + \"` value cannot be negative: \" + value);\n        }\n        return value;\n    }\n\n    private static String prefixTag(final boolean isTagged, final Long value)\n    {\n        return isTagged ? TAG_PREFIX + value : value.toString();\n    }\n}","sourceCodeStart":2535,"sourceCodeEnd":2571,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L2535-L2571","documentation":"Thrown by ChannelUriStringBuilder's private requireNonNegative(Long, String) helper when an optional numeric URI field is set to a negative Long value. The builder refuses to emit channel URIs with negative sizes/ids because the media driver would reject or misinterpret them.","triggerScenarios":"Setting a Long-typed builder field (e.g. initialWindowLength, termBufferLength, session-id related tagged values) via a setter that runs requireNonNegative with a negative value such as -1.","commonSituations":"Using -1 as a sentinel 'unset' value when configuring from properties; unsigned sizes computed with arithmetic underflow (e.g. capacity - overhead going negative).","solutions":["Use a positive value for the named field (the exception message contains the field name and value).","Leave the field null/unset instead of using -1 as a sentinel.","Clamp or validate values computed from arithmetic before passing them to the builder."],"exampleFix":"// before\nlong window = computeWindow(); // may be -1 when missing\nbuilder.initialWindowLength(window);\n// after\nif (window >= 0) builder.initialWindowLength(window); // otherwise leave unset","handlingStrategy":"validation","validationCode":"if (value != null && value < 0) throw new IllegalArgumentException(name + \" must be non-negative, got \" + value);\nbuilder.initialWindowLength(value);","typeGuard":null,"tryCatchPattern":"try { uri = builder.build(); } catch (IllegalArgumentException e) { /* includes non-negative violations; log field name from message */ log.error(\"invalid channel field: {}\", e.getMessage()); }","preventionTips":["Do not use -1 as an 'unset' sentinel; leave fields null.","Guard arithmetic that can underflow below zero.","Validate all sizes when loading config, before building the URI."],"tags":["java","aeron","channel-uri","negative-value"],"backgroundTag":"invalid-argument-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}