apache/beam · error · IllegalArgumentException

illegal hex digit

Error message

illegal hex digit

What it means

hexValue maps a single character to its hexadecimal value (0–9, a–f, A–F). Any other character found in a \u or \U escape sequence throws IllegalArgumentException("illegal hex digit"). Hex escapes in Firestore field names must consist exclusively of hex digits.

Solutions

1. Replace every non-hex character inside the escape with a valid hex digit (0-9, a-f, A-F).
2. Expand placeholder escapes (e.g. \uXXXX) with the actual code point before use.
3. Generate escaped names with tooling instead of typing them manually.
4. Validate the escaped field name with a regex like \\u[0-9a-fA-F]{4} before passing it in.

Example fix

// before
String field = "\u00G1x"; // 'G' is not a hex digit
// after
String field = "\u00A1x"; // valid hex digits

// Java: ensure \u/\U escapes contain only hex digits
static boolean hexDigitsValid(String name) {
  java.util.regex.Matcher m =
      java.util.regex.Pattern.compile("\\\\[uU]([0-9a-fA-F]*)") .matcher(name);
  int end = 0;
  while (m.find(end)) {
    if (m.group(1).length() == 0) return false; // placeholder like \uXXXX
    end = m.end();
  }
  return name.indexOf("\\u") < 0 || end > 0;
}

try {
  String decoded = QueryUtils.unescaped(fieldName);
} catch (IllegalArgumentException e) {
  LOG.warn("Non-hex digit in unicode escape: %s", fieldName, e);
}

When it happens

Trigger: A \u or \U escape containing a non-hex character, e.g. "\u00G1" or "\U0000 041" (embedded space), decoded by unescapeFieldName through unescapeHex.

Common situations: Hand-written escapes with typos ('O' instead of '0', 'g' instead of '9'); escapes truncated or mangled by string formatting; placeholders like \uXXXX left unexpanded in generated code.

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

• illegal codepoint
• illegal escape
• illegal octal digit
• illegal hex escape sequence
• illegal octal escape sequence

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/319930b3138e47b8. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/QueryUtils.java:393

    }

    private static int octalValue(char d) {
      if (d >= '0' && d <= '7') {
        return d - '0';
      } else {
        throw new IllegalArgumentException("illegal octal digit");
      }
    }

    private static int hexValue(char d) {
      if (d >= '0' && d <= '9') {
        return d - '0';
      } else if (d >= 'a' && d <= 'f') {
        return 10 + d - 'a';
      } else if (d >= 'A' && d <= 'F') {
        return 10 + d - 'A';
      } else {
        throw new IllegalArgumentException("illegal hex digit");
      }
    }
  }
}

View on GitHub (pinned to 12126d8942)