signalapp/Signal-Server · error · FieldValidationException

value is not valid base64 url

Error message

value is not valid base64 url

What it means

Base64UrlFieldValidator validates that a proto field value is decodable base64url. It runs java.util.Base64.getUrlDecoder().decode on the string and throws FieldValidationException('value is not valid base64 url') on IllegalArgumentException, causing the gRPC request to be rejected.

Solutions

1. Encode the value with URL-safe base64 (no padding issues: use base64url with or without padding as the schema expects)
2. Replace '+' with '-' and '/' with '_' if you only have standard base64
3. Check that you are not sending hex (bytesToHex) where base64url is expected
4. Inspect the offending field value for whitespace, quotes, or truncation before sending

Example fix

// before
String encoded = Base64.getEncoder().encodeToString(bytes);
// after
String encoded = Base64.getUrlEncoder().encodeToString(bytes);

boolean isValidBase64Url(String s) {
  if (s == null || s.isEmpty()) return false;
  try { Base64.getUrlDecoder().decode(s); return true; } catch (IllegalArgumentException e) { return false; }
}

try {
  grpcStub.call(request);
} catch (StatusRuntimeException e) {
  if (e.getStatus().getCode() == Code.INVALID_ARGUMENT && e.getStatus().getDescription().contains("base64 url")) {
    // re-encode the offending field with Base64.getUrlEncoder()
  }
}

When it happens

Trigger: gRPC requests (e.g. receipts, backup, account fields annotated with this validator) carrying a string field that is empty, standard base64 with '+'/'/', hex-encoded, or otherwise not valid base64url (A-Z, a-z, 0-9, '-', '_').

Common situations: Clients using standard base64 instead of base64url, hex or raw bytes encoded as a string, corrupted/truncated values from key derivation code, double encoding.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• enum field must be specified
• value is not in E164 format
• 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/b2c786f5cd8bf3af. Report an issue: GitHub.

Appendix: source

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

public class Base64UrlFieldValidator extends FieldValidator<Boolean> {

  public Base64UrlFieldValidator() {
    super("base64url", 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 {
      Base64.getUrlDecoder().decode(fieldValue);
    } catch (IllegalArgumentException e) {
      throw new FieldValidationException("value is not valid base64 url");
    }
  }
}

View on GitHub (pinned to 100ab61c82)