apache/flink · error · IllegalArgumentException

Cannot parse JobID from "{hexString}". The expected format i

Error message

Cannot parse JobID from "{hexString}". The expected format is [0-9a-fA-F]{32}, e.g. fd72014d4c864993a2e5a9287b4a9c5d.

What it means

Thrown by JobID.fromHexString when the input cannot be decoded into the 16-byte (128-bit) JobID. A JobID's hex form must be exactly 32 hex characters. Malformed input (wrong length, non-hex characters, null) makes StringUtils.hexStringToByte throw, which is wrapped into this IllegalArgumentException showing the bad value and the expected format.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/JobID.java:108

    public static JobID fromByteBuffer(ByteBuffer buf) {
        long lower = buf.getLong();
        long upper = buf.getLong();
        return new JobID(lower, upper);
    }

    /**
     * Parses a JobID from the given string.
     *
     * @param hexString string representation of a JobID
     * @return Parsed JobID
     * @throws IllegalArgumentException if the JobID could not be parsed from the given string
     */
    public static JobID fromHexString(String hexString) {
        try {
            return new JobID(StringUtils.hexStringToByte(hexString));
        } catch (Exception e) {
            throw new IllegalArgumentException(
                    "Cannot parse JobID from \""
                            + hexString
                            + "\". The expected format is "
                            + "[0-9a-fA-F]{32}, e.g. fd72014d4c864993a2e5a9287b4a9c5d.",
                    e);
        }
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

Validate with ^[0-9a-fA-F]{32}$ and trim before calling fromHexString.
Only ever persist the output of JobID.toString()/toHexString() and read it back verbatim.
When sourcing from URLs/JSON, decode and trim first, and assert length 32.

Example fix

// before
JobID id = JobID.fromHexString(raw);
// after
String hex = raw == null ? "" : raw.trim();
if (!hex.matches("[0-9a-fA-F]{32}")) {
    throw new IllegalArgumentException("Invalid JobID: " + raw);
}
JobID id = JobID.fromHexString(hex);

Defensive patterns

Strategy: validation

Validate before calling

String hex = hexString == null ? "" : hexString.trim();
if (!hex.matches("[0-9a-fA-F]{32}")) {
    throw new IllegalArgumentException("Invalid JobID hex: " + hexString);
}
JobID id = JobID.fromHexString(hex);

Type guard

public static boolean isValidJobIdHex(String s) {
    return s != null && s.trim().matches("[0-9a-fA-F]{32}");
}

Try / catch

try { JobID id = JobID.fromHexString(raw); }
catch (IllegalArgumentException e) { /* reject malformed id */ }

Prevention

Only persist JobIDs via toString()/toHexString().
Trim and validate external strings before parsing.
Decode URL/JSON-escaped values before validation.

When it happens

Trigger: Calling JobID.fromHexString(bad) with null, wrong-length, or non-hex input; round-tripping a JobID through a layer that altered the string; confusing JobID with a numeric job sequence id.

Common situations: Parsing JobID from a REST URL path, log, or savepoint metadata file that included whitespace or a prefix; copy-paste truncation; JSON keys whose value carried quotes or escaping.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/06ab82e8c717f35d. Report an issue: GitHub.