signalapp/Signal-Server · error · FieldValidationException

field value is [ ] but expected to be within the [ , ] range

Error message

field value is [%d] but expected to be within the [%d, %d] range

What it means

RangeFieldValidator.validateIntegerNumber throws FieldValidationException when an integer field value falls outside the annotated [min, max] range for the field. The message includes the actual value and the allowed range.

Solutions

1. Clamp or validate the integer against the documented range before sending
2. Generate IDs per the protocol spec's valid ranges
3. Read the server's range annotation for the field and enforce it in client validation

Example fix

// before
int regId = new Random().nextInt();
builder.setRegistrationId(regId);
// after
int regId = new SecureRandom().nextInt(16777216); // 0..16777215
builder.setRegistrationId(regId);

if (value < MIN || value > MAX) throw new IllegalArgumentException("value " + value + " outside [" + MIN + ", " + MAX + "]");

boolean inRange(long v, long min, long max) { return v >= min && v <= max; }

try { stub.call(request); } catch (StatusRuntimeException e) { if (e.getStatus().getCode() == Status.Code.INVALID_ARGUMENT && e.getMessage().contains("range")) { /* handle out-of-range */ } }

When it happens

Trigger: Sending a Signal gRPC request with an integer field (e.g. device ID, registration ID, count) whose value exceeds or falls below the range annotation, such as deviceId 0 or registrationId outside 0..16777215.

Common situations: Off-by-one usage of IDs starting at 1 vs 0; clients generating random values without bounds; version skew where server-side range annotations tightened.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• field value is expected to be within the
• value is not valid base64 url
• value is not in E164 format
• enum field must be specified
• byte array length is

AI-assisted analysis of signalapp/Signal-Server@100ab61c82 (2026-09-09). Data as JSON: /api/errors/01185147aa7144e8. Report an issue: GitHub.

Appendix: source

Thrown at service/src/main/java/org/whispersystems/textsecuregcm/grpc/validators/RangeFieldValidator.java:54

  @Override
  protected Range resolveExtensionValue(final Object extensionValue) {
    final ValueRangeConstraint rangeConstraint = (ValueRangeConstraint) extensionValue;
    final long min = rangeConstraint.hasMin() ? rangeConstraint.getMin() : Long.MIN_VALUE;
    final long max = rangeConstraint.hasMax() ? rangeConstraint.getMax() : Long.MAX_VALUE;
    return new Range(min, max);
  }

  @Override
  protected void validateIntegerNumber(
      final Range range,
      final long fieldValue,
      final Descriptors.FieldDescriptor.Type type) throws FieldValidationException {
    if (fieldValue < 0 && UNSIGNED_TYPES.contains(type)) {
      throw new FieldValidationException("field value is expected to be within the [%d, %d] range".formatted(
          range.min(), range.max()));
    }
    if (fieldValue < range.min() || fieldValue > range.max()) {
      throw new FieldValidationException("field value is [%d] but expected to be within the [%d, %d] range".formatted(
          fieldValue, range.min(), range.max()));
    }
  }
}

View on GitHub (pinned to 100ab61c82)