microg/GmsCore · error · IllegalArgumentException

the id is not of length 16 bytes

Error message

the id is not of length 16 bytes

What it means

ThreadBorderAgent.newBuilder(byte[] id) validates that the Border Agent identifier is exactly 16 bytes and throws IllegalArgumentException otherwise. Thread Border Agent IDs are defined by the Thread specification as 16-byte UUID-like values, so any other length cannot be a valid identifier.

Source

Thrown at play-services-threadnetwork/src/main/java/com/google/android/gms/threadnetwork/ThreadBorderAgent.java:44

    public ThreadBorderAgent(@Param(2) byte[] id) {
        this.id = id;
    }

    /**
     * Returns the id which uniquely identifies a Thread Border Agent device.
     */
    public byte[] getId() {
        return id;
    }

    /**
     * Creates a new {@link ThreadBorderAgent.Builder} for constructing a {@link ThreadBorderAgent}.
     *
     * @param id the id which uniquely identifies a Border Agent. The length must be 16 bytes.
     * @throws IllegalArgumentException if the id is not of length 16 bytes.
     */
    public static Builder newBuilder(byte[] id) {
        if (id.length != 16) throw new IllegalArgumentException("the id is not of length 16 bytes");
        return new Builder(id);
    }

    /**
     * Builder for constructing {@link ThreadBorderAgent} instances.
     */
    public static class Builder {
        private byte[] id;

        private Builder(byte[] id) {
            this.id = id;
        }

        /**
         * Constructs a {@link ThreadBorderAgent} as configured by this builder.
         */
        public ThreadBorderAgent build() {
            return new ThreadBorderAgent(id);

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Verify id.length == 16 before calling newBuilder and reject/repair the input
2. Re-encode the identifier correctly: parse as a 16-byte UUID (UUID.toString/fromString maps to 16 bytes)
3. If hex-decoding, confirm the hex string is 32 characters and decode without trimming
4. Log the actual length to find where the ID got truncated or padded

Example fix

// before
byte[] id = hexStringToByteArray(agentHex); // may be wrong length
ThreadBorderAgent agent = ThreadBorderAgent.newBuilder(id).build();
// after
byte[] id = hexStringToByteArray(agentHex);
if (id.length != 16) throw new IllegalArgumentException("Border agent id must be 16 bytes, got " + id.length);
ThreadBorderAgent agent = ThreadBorderAgent.newBuilder(id).build();

if (id == null || id.length != 16) throw new IllegalArgumentException("Border agent id must be exactly 16 bytes, got " + (id == null ? "null" : id.length));

boolean isValidBorderAgentId(byte[] id) { return id != null && id.length == 16; }

try {
    ThreadBorderAgent.Builder b = ThreadBorderAgent.newBuilder(id);
} catch (IllegalArgumentException e) {
    // log and reject the malformed identifier
}

When it happens

Trigger: Passing a byte[] whose length is not 16 to ThreadBorderAgent.newBuilder() — e.g. a truncated copy, a hex/base64-decoded string of the wrong length, or a raw device-reported ID of 8 bytes.

Common situations: Decoding a border agent ID from a string (hex/base64) that drops leading zeros or includes separators; receiving IDs from an API that returns shorter identifiers; copy-pasting an ID with wrong 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

• length of flags is smaller than LENGTH_MIN_SECURITY_POLICY_F
• page exceeds range [0, 255].
• rotationTimeHours is not in range of 0x1-0xffff
• deleteAll was set to true but keys were also provided
• Element in keys cannot be null or empty

AI-assisted analysis of microg/GmsCore@157c9d86ac (2026-09-06). Data as JSON: /api/errors/97a4b82960eb5214. Report an issue: GitHub.