signalapp/Signal-Server · error · FieldValidationException

value is not in E164 format

Error message

value is not in E164 format

What it means

E164FieldValidator checks that a proto field string is a normalized E.164 phone number via Util.requireNormalizedNumber. ImpossiblePhoneNumberException (unparseable) or NonNormalizedPhoneNumberException (parseable but not in strict E.164 form) result in FieldValidationException('value is not in E164 format').

Solutions

1. Normalize with libphonenumber: PhoneNumberUtil.format(number, PhoneNumberFormat.E164) before sending
2. Ensure the value starts with '+' followed by country code and subscriber number, digits only
3. Strip spaces, dashes, parentheses, and extensions
4. Validate locally (parse + isPossibleNumber) before making the API call

Example fix

// before
String e164 = "(415) 555-2671";
// after
String e164 = "+14155552671"; // via PhoneNumberUtil.format(..., E164)

PhoneNumberUtil util = PhoneNumberUtil.getInstance();
Phonenumber.PhoneNumber n = util.parse(rawNumber, null);
String e164 = util.format(n, PhoneNumberUtil.PhoneNumberFormat.E164);
if (!e164.equals(rawNumber)) throw new IllegalArgumentException("number must be pre-normalized to E164: " + e164);

static boolean isE164(String s) { return s != null && s.matches("\\+\\d{1,15}"); }

try {
  grpcStub.callNumberField(e164);
} catch (StatusRuntimeException e) {
  if (e.getStatus().getCode() == Code.INVALID_ARGUMENT && e.getStatus().getDescription().contains("E164")) {
    // re-normalize with libphonenumber and retry
  }
}

When it happens

Trigger: gRPC requests with phone number fields containing local formats, spaces/dashes/parentheses, missing '+' prefix, leading double zeros (0044...), or extensions.

Common situations: Users entering numbers from a contacts app in national format; clients skipping libphonenumber normalization before calling the API; numbers with country code but stray punctuation after device migration.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• value is not valid base64 url
• enum field must be specified
• byte array length is
• string length is [ ] but expected to be one of
• list size is [ ] but expected to be one of

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

Appendix: source

Thrown at service/src/main/java/org/whispersystems/textsecuregcm/grpc/validators/E164FieldValidator.java:32

public class E164FieldValidator extends FieldValidator<Boolean> {

  public E164FieldValidator() {
    super("e164", Set.of(Descriptors.FieldDescriptor.Type.STRING), MissingOptionalAction.SUCCEED, false);
  }

  @Override
  protected Boolean resolveExtensionValue(final Object extensionValue) throws FieldValidationException {
    return requireFlagExtension(extensionValue);
  }

  @Override
  protected void validateStringValue(
      final Boolean extensionValue,
      final String fieldValue) throws FieldValidationException {
    try {
      Util.requireNormalizedNumber(fieldValue);
    } catch (final ImpossiblePhoneNumberException | NonNormalizedPhoneNumberException e) {
      throw new FieldValidationException("value is not in E164 format");
    }
  }
}

View on GitHub (pinned to 100ab61c82)