apache/maven · error · BuilderNotFoundException

The builder requested using id = %s cannot be found

Error message

The builder requested using id = %s cannot be found

What it means

DefaultLifecycleStarter resolves the builder from a map of registered Builder components using the id from MavenExecutionRequest.getBuilderId() (set by -b/--builder). If no Builder component is registered under that id, the session aborts with BuilderNotFoundException before the reactor starts.

Source

Thrown at impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/DefaultLifecycleStarter.java:112

            if (projectBuilds.isEmpty()) {
                throw new NoGoalSpecifiedException("No goals have been specified for this build."
                        + " You must specify a valid lifecycle phase or a goal in the format <plugin-prefix>:<goal> or"
                        + " <plugin-group-id>:<plugin-artifact-id>[:<plugin-version>]:<goal>."
                        + " Available lifecycle phases are: " + defaultLifeCycles.getLifecyclePhaseList() + ".");
            }

            if (logger.isDebugEnabled()) {
                lifecycleDebugLogger.debugReactorPlan(projectBuilds);
            }

            ClassLoader oldContextClassLoader = Thread.currentThread().getContextClassLoader();
            ReactorBuildStatus reactorBuildStatus = new ReactorBuildStatus(session.getProjectDependencyGraph());
            reactorContext = new ReactorContext(result, oldContextClassLoader, reactorBuildStatus);

            String builderId = session.getRequest().getBuilderId();
            Builder builder = builders.get(builderId);
            if (builder == null) {
                throw new BuilderNotFoundException(
                        String.format("The builder requested using id = %s cannot be" + " found", builderId));
            }

            int degreeOfConcurrency = session.getRequest().getDegreeOfConcurrency();
            if (degreeOfConcurrency > 1) {
                logger.info("");
                logger.info(String.format(
                        "Using the %s implementation with a thread count of %d",
                        builder.getClass().getSimpleName(), degreeOfConcurrency));
            }
            builder.build(session, reactorContext, projectBuilds, taskSegments, reactorBuildStatus);

        } catch (Exception e) {
            result.addException(e);
        } finally {
            eventCatapult.fire(ExecutionEvent.Type.SessionEnded, session, null);
        }
    }

View on GitHub (pinned to e4093d4e12)

Solutions

1. Use a stock builder id: mvn -b multithreaded (default) or -b singlethreaded
2. If a custom builder is intended, add the extension that provides it to the project (core extension in .mvn/extensions.xml or build extension) so the component gets registered
3. Remove or fix the -b/--builder flag in .mvn/maven.config, MAVEN_ARGS, or the CI command
4. Run with -X to see the available builder ids registered in the container

Example fix

# before
mvn -b mycustombuilder package   # no such Builder -> BuilderNotFoundException

# after
mvn -b multithreaded package
# or register the builder via .mvn/extensions.xml and keep -b mycustombuilder

// verify the builder id is registered before starting the session
if (!builders.containsKey(request.getBuilderId())) {
    throw new IllegalArgumentException("Unknown builder id: " + request.getBuilderId()
        + ", available: " + builders.keySet());
}

catch (BuilderNotFoundException e) {
    // fall back to the default 'multithreaded' builder or load the missing extension and retry
}

When it happens

Trigger: Running mvn -b someId where someId is neither a built-in id (e.g. 'singlethreaded', 'multithreaded') nor a Builder contributed by a loaded extension; typo in the builder id in .mvn/maven.config or CI args; an extension that used to register the builder not being applied (deactivated profile, removed extension).

Common situations: Copying -b config from a project whose custom builder extension is not present in yours; -Dmaven.builder=id typos; migrating CI images to a Maven distribution missing the extension that provides the builder.

Related errors

• Error building settings
• Error building toolchains
• Only fully-qualified sets allowed in multiple set scenario:
• Single version must be surrounded by []: {}
• The artifact has no valid ranges

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