apache/seatunnel · warning · JdbcConnectorException

COMMON_ILLEGAL_ARGUMENT

COMMON_ILLEGAL_ARGUMENT

Error message

bytes == null

What it means

XidImpl.byteToHexString renders XID branch/global qualifier bytes as a hex string for logging/comparison. It validates its input first and throws ILLEGAL_ARGUMENT with 'bytes == null' when a null byte array is passed, since a null qualifier cannot be rendered.

Solutions

1. Ensure Xid instances are built with non-null globalTransactionId and branchQualifier arrays (use empty arrays instead of null).
2. Validate/normalize Xid data before passing it into XidImpl utility methods.
3. Guard the call site with a null check and substitute a placeholder like "" or "null" for logging.
4. Fix the upstream producer of the Xid (checkpoint deserialization or driver recovery) that returned null bytes.

Example fix

// before
String s = XidImpl.byteToHexString(xid.getBranchQualifier(), 0, xid.getBranchQualifier().length);
// after
byte[] bq = xid.getBranchQualifier();
String s = bq == null ? "" : XidImpl.byteToHexString(bq, 0, bq.length);

if (bytes == null) {
  bytes = new byte[0]; // or skip formatting entirely
}

String safeHex(byte[] b) {
  return b == null ? "" : XidImpl.byteToHexString(b, 0, b.length);
}

try {
  String s = XidImpl.byteToHexString(bytes, start, end);
} catch (JdbcConnectorException e) {
  if (CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT.equals(e.getErrorCode())) {
    log.warn("Xid qualifier bytes were null; using placeholder");
  }
}

When it happens

Trigger: Calling byteToHexString(bytes, start, end) (or the overload that delegates to it) with a null byte[] — typically when an Xid was constructed with null branch/global qualifier bytes and then formatted.

Common situations: Custom Xid construction with missing globalTransactionId or branchQualifier; deserializing a corrupt/foreign Xid from a checkpoint state; driver returning an Xid with null fields during recovery.

Related errors

• begin next transaction failed, rollback prepared…
• CLASS_NOT_FOUND
• COMMON_UNSUPPORTED_OPERATION
• COMMON_WRITER_OPERATION_FAILED
• COMMON_WRITER_OPERATION_FAILED

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/b6b7fe1faf0ebc79. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/xa/XidImpl.java:115

                + ":"
                + byteToHexString(branchQualifier);
    }

    /**
     * Given an array of bytes it will convert the bytes to a hex string representation of the
     * bytes.
     *
     * @param bytes the bytes to convert in a hex string
     * @param start start index, inclusively
     * @param end end index, exclusively
     * @return hex string representation of the byte array
     */
    public static String byteToHexString(final byte[] bytes, final int start, final int end) {
        final int number0xf0 = 0xF0;
        final int number0x0f = 0x0F;
        final int number4 = 4;
        if (bytes == null) {
            throw new JdbcConnectorException(
                    CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT, "bytes == null");
        }

        int length = end - start;
        char[] out = new char[length * 2];

        for (int i = start, j = 0; i < end; i++) {
            out[j++] = HEX_CHARS[(number0xf0 & bytes[i]) >>> number4];
            out[j++] = HEX_CHARS[number0x0f & bytes[i]];
        }

        return new String(out);
    }

    /**
     * Given an array of bytes it will convert the bytes to a hex string representation of the
     * bytes.
     *

View on GitHub (pinned to cf67b549a7)