apache/maven · error · SettingsBuilderException

Error building settings

Error message

Error building settings

What it means

Thrown by DefaultSettingsBuilder.build when the merged settings (installation, user and project sources) accumulate error-severity problems, for example an unparseable settings.xml. The exception carries the full ProblemCollector of BuilderProblem entries; iterating them gives each message and source location. Note the builder resolves a relative localRepository to an absolute path before the error check.

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/DefaultSettingsBuilder.java:142

            effective = Settings.newBuilder(effective)
                    .repositories(List.of(central))
                    .pluginRepositories(List.of(centralWithNoUpdate))
                    .build();
        }

        // resolve relative local repository paths to absolute to save plugins from trouble.
        // paths containing property placeholders like ${user.home} must be left as-is
        // so that later interpolation can resolve them.
        String localRepository = effective.getLocalRepository();
        if (localRepository != null && !localRepository.isEmpty()) {
            Path file = Paths.get(localRepository);
            if (!file.isAbsolute() && !localRepository.contains("${")) {
                effective = effective.withLocalRepository(file.toAbsolutePath().toString());
            }
        }

        if (problems.hasErrorProblems()) {
            throw new SettingsBuilderException("Error building settings", problems);
        }

        return new DefaultSettingsBuilderResult(request, effective, problems);
    }

    private Settings readSettings(
            Source settingsSource,
            boolean isProjectSettings,
            SettingsBuilderRequest request,
            ProblemCollector<BuilderProblem> problems) {
        if (settingsSource == null) {
            return Settings.newInstance();
        }

        Settings settings;

        try {
            try (InputStream is = settingsSource.openStream()) {

View on GitHub (pinned to e4093d4e12)

Solutions

1. Catch SettingsBuilderException and iterate the attached problem collector - each problem names its file and line
2. Fix or reformat the settings.xml at the reported location
3. Temporarily replace the offending settings file with a minimal valid one to confirm which source is at fault

Example fix

// before
SettingsBuilderResult result = settingsBuilder.build(request);

// after
try {
    SettingsBuilderResult result = settingsBuilder.build(request);
} catch (SettingsBuilderException e) {
    e.getProblemCollector().getProblems()
        .forEach(p -> log.error("{}: {}", p.getLocation(), p.getMessage()));
}

try {
    SettingsBuilderResult result = settingsBuilder.build(request);
} catch (SettingsBuilderException e) {
    e.getProblemCollector().getProblems()
        .forEach(p -> log.error("{}: {}", p.getLocation(), p.getMessage()));
    // degrade gracefully: fall back to defaults or a minimal settings file
}

When it happens

Trigger: A settings.xml source (global, user, or .mvn project settings) with XML parse errors or values the reader reports as ERROR severity; SettingsBuilderRequest sources that exist but cannot be read or interpolated.

Common situations: Hand-edited ~/.m2/settings.xml with unclosed tags; CI provisioning that truncates settings files; sharing settings files between Maven versions where validation strictness differs.

Related errors

• The specified user settings file does not exist: {}
• The specified project settings file does not exist: {}
• The specified installation settings file does not exist: {}
• The builder requested using id = %s cannot be found
• Error building toolchains

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