apache/beam · error · IllegalArgumentException

illegal octal digit

Error message

illegal octal digit

What it means

octalValue maps a single character to its octal value (0–7). Any character outside '0'–'7' — such as '8', '9', or a letter — encountered in an octal escape sequence throws IllegalArgumentException("illegal octal digit"). The escape grammar only permits octal digits in that position.

Solutions

  1. Use only digits 0–7 in octal escape sequences.
  2. Convert decimal escapes to octal form (e.g. \9 -> \11) or switch to a \uXXXX hex escape.
  3. Remove the backslash if the sequence was not intended as an escape.
  4. Escape field names programmatically with the library's escaping logic rather than by hand.

Example fix

// before
String field = "item\98desc"; // 9 and 8 are not octal digits
// after
String field = "item\u0038desc"; // hex escape for the intended character
Defensive patterns

Strategy: validation

Validate before calling

// Java: check all octal escape digits are 0-7
static boolean octalDigitsValid(String name) {
  java.util.regex.Matcher m =
      java.util.regex.Pattern.compile("\\\\([^uU0-7])(.*)").matcher(name);
  return !m.find();
}

Try / catch

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

Prevention

When it happens

Trigger: A backslash followed by digits including 8 or 9, e.g. "a\98b", parsed by unescapeOctal via unescapeFieldName — '9' is not an octal digit.

Common situations: Decimal escapes mistakenly written where octal escapes are expected (\9 meaning character 9); copy-pasted escapes from languages with decimal escape semantics; typos in hand-written escaped field names.

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

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/c0ee4bf705483b9a. 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:381

      return ch;
    }

    private static int unescapeHex(String str) {
      int ch = 0;
      for (int i = 0; i < str.length(); i++) {
        ch = 16 * ch + hexValue(str.charAt(i));
      }
      if (!Character.isValidCodePoint(ch)) {
        throw new IllegalArgumentException("illegal codepoint");
      }
      return ch;
    }

    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)