apache/maven · error · XmlReaderException

Unable to read settings:

Error message

Unable to read settings: 

What it means

Wrapper thrown when parsing a Settings document fails: malformed settings.xml, strict-mode rejection of unknown elements, or IO errors while reading the supplied Reader/InputStream. The cause is preserved; STaX causes carry line and column information that this factory appends to the message.

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/DefaultSettingsXmlFactory.java:70

        if (reader == null && inputStream == null) {
            throw new IllegalArgumentException("reader or inputStream must be non null");
        }
        try {
            InputSource source = null;
            if (request.getModelId() != null || request.getLocation() != null) {
                source = InputSource.of(request.getLocation());
            }
            SettingsStaxReader xml = request.getTransformer() != null
                    ? new SettingsStaxReader(request.getTransformer()::transform)
                    : new SettingsStaxReader();
            xml.setAddDefaultEntities(request.isAddDefaultEntities());
            if (reader != null) {
                return xml.read(reader, request.isStrict(), source);
            } else {
                return xml.read(inputStream, request.isStrict(), source);
            }
        } catch (Exception e) {
            throw new XmlReaderException("Unable to read settings: " + getMessage(e), getLocation(e), e);
        }
    }

    @Override
    public void write(XmlWriterRequest<Settings> request) throws XmlWriterException {
        nonNull(request, "request");
        Settings content = nonNull(request.getContent(), "content");
        OutputStream outputStream = request.getOutputStream();
        Writer writer = request.getWriter();
        if (writer == null && outputStream == null) {
            throw new IllegalArgumentException("writer or outputStream must be non null");
        }
        try {
            SettingsStaxWriter xmlWriter = new SettingsStaxWriter();
            xmlWriter.setAddLocationInformation(false);

            Function<Object, String> formatter = request.getInputLocationFormatter();
            if (formatter != null) {

View on GitHub (pinned to e4093d4e12)

Solutions

1. Unwrap getCause() for the exact line and column of the parse failure
2. Try .strict(false) on the request if unknown elements are acceptable
3. Check encoding and well-formedness with an XML lint tool before passing the file
4. If entity expansion is involved, review the request's addDefaultEntities setting

Example fix

// before
Settings s = settingsXmlFactory.read(XmlReaderRequest.builder()
    .reader(reader)
    .build()); // strict default can reject unknown elements

// after
Settings s = settingsXmlFactory.read(XmlReaderRequest.builder()
    .reader(reader)
    .strict(false)
    .build());

try {
    Settings s = settingsXmlFactory.read(req);
} catch (XmlReaderException e) {
    Throwable cause = e.getCause();
    // STaX cause carries line/column; surface it, do not retry blindly
    log.error("settings parse failed: {}", e.getMessage(), cause);
}

When it happens

Trigger: Malformed or truncated settings.xml fed via reader/inputStream; strict=true with unrecognized tags; a stream that throws during read; wrong character encoding producing parse failures.

Common situations: Corrupted user settings after a crashed editor; settings files saved in an unexpected encoding; settings with constructs (entities, DTDs) the reader rejects.

Related errors

• Unable to read plugin:
• reader or inputStream must be non null
• writer or outputStream must be non null
• Unable to write settings: {}
• Unable to read toolchains: {}

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