apache/maven · error · XMLStreamException

Unable to parse element '{}', must be a byte

Error message

Unable to parse element '{}', must be a byte

What it means

This message is thrown by the StAX model reader generated from src/mdo/reader.vm (the Modello template behind readers like MetadataStaxReader and MavenStaxReader) when a model XML field typed as byte contains text that Byte.valueOf(String) cannot parse. In strict parsing mode (the default for most generated readers) the helper getByteValue rethrows the NumberFormatException as a javax.xml.stream.XMLStreamException, aborting the whole document parse. In non-strict mode the error is swallowed and the field silently defaults to 0.

Source

Thrown at src/mdo/reader.vm:792

    /**
     * Method getByteValue.
     *
     * @param s a s object.
     * @param strict a strict object.
     * @param parser a parser object.
     * @param attribute a attribute object.
     * @throws XMLStreamException XMLStreamException if
     * any.
     * @return byte
     */
    private byte getByteValue(String s, String attribute, XMLStreamReader parser, boolean strict)
        throws XMLStreamException {
        if (s != null) {
            try {
                return Byte.valueOf(s).byteValue();
            } catch (NumberFormatException nfe) {
                if (strict) {
                    throw new XMLStreamException("Unable to parse element '" + attribute + "', must be a byte", parser.getLocation(), nfe);
                }
            }
        }
        return 0;
    } //-- byte getByteValue(String, String, XMLStreamReader, boolean)

    /**
     * Method getCharacterValue.
     *
     * @param s a s object.
     * @param parser a parser object.
     * @param attribute a attribute object.
     * @throws XMLStreamException XMLStreamException if
     * any.
     * @return char
     */
    private char getCharacterValue(String s, String attribute, XMLStreamReader parser)
        throws XMLStreamException {

View on GitHub (pinned to e4093d4e12)

Solutions

1. Open the file named in the exception location, find the offending element, and put a valid byte (-128 to 127) in it.
2. If the file is derived (maven-metadata-*.xml, plugin metadata), delete the local copy and let Maven re-download it instead of hand-fixing it.
3. If you control the caller and can tolerate defaults, invoke the reader with strict=false so malformed values fall back to 0 instead of aborting.
4. Regenerate/repair the producer that wrote the bad value so the error does not recur on next write.

Example fix

<!-- before: mdo model XML -->
<myByteField>300</myByteField>
<!-- after -->
<myByteField>127</myByteField>

// before
Metadata md = new MetadataStaxReader().read(file, true); // XMLStreamException

// after
try {
    Metadata md = new MetadataStaxReader().read(file, true);
} catch (XMLStreamException e) {
    Files.deleteIfExists(file.toPath()); // force re-download of derived metadata
}

byte checkByte(String s) { return Byte.parseByte(s.trim()); } // run on the raw text before handing the XML to the reader

try {
    Model m = new GeneratedStaxReader().read(file, true);
} catch (XMLStreamException e) {
    // message names the offending attribute; location gives line/column
    log.warn("model parse failed at " + e.getLocation().getLineNumber(), e);
}

When it happens

Trigger: Calling a generated reader such as new MetadataStaxReader().read(inputStream, strict=true) or MavenStaxReader.read(...) on XML where a byte-typed element/attribute holds 'abc', an empty string, a decimal like '1.5', or a value outside -128..127. Only reachable for models that actually declare a byte field; the read fails on the first malformed value.

Common situations: Hand-edited maven-metadata.xml or other model files with typos in numeric fields; files written by a buggy custom plugin; byte field overflow (e.g. '255') from tools that do not clamp byte ranges; CI caches poisoned with a truncated download.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unable to parse element '{}', must be a floating point numbe
• Unable to parse element '{}', must be an integer
• Unable to parse element '{}', must be a long integer
• Unable to parse element '{}', must be a short integer
• Entities are not supported in strict mode

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/53eedaa7daefc952. Report an issue: GitHub.