quarkusio/quarkus · error · BootstrapMavenException

Top-level project base directory <dir> specified with system

Error message

Top-level project base directory <dir> specified with system property maven.top.level.project.basedir does not exist

What it means

DevMojo honors the maven.top.level.project.basedir system property to locate the root directory of a multi-module build. If the property is set but the path it points to does not exist on disk, BootstrapMavenException is thrown with this message. The property is typically used by IDEs or tooling to override Maven's notion of the top-level project.

Source

Thrown at devtools/maven/src/main/java/io/quarkus/maven/DevMojo.java:1523

        }

        setKotlinSpecificFlags(builder);
        setAnnotationProcessorFlags(builder);

        // path to the serialized application model
        final Path appModelLocation = resolveSerializedModelLocation();

        ApplicationModel appModel = bootstrapProvider.getResolvedApplicationModel(
                QuarkusBootstrapProvider.getProjectId(project), getLaunchModeClasspath(), bootstrapId);
        if (appModel != null) {
            bootstrapProvider.close();
        } else {
            Path rootProjectDir = null;
            String topLevelBaseDirStr = systemProperties.get(BootstrapMavenContext.MAVEN_TOP_LEVEL_PROJECT_BASEDIR);
            if (topLevelBaseDirStr != null) {
                final Path tmp = Path.of(topLevelBaseDirStr);
                if (!Files.exists(tmp)) {
                    throw new BootstrapMavenException("Top-level project base directory " + topLevelBaseDirStr
                            + " specified with system property " + BootstrapMavenContext.MAVEN_TOP_LEVEL_PROJECT_BASEDIR
                            + " does not exist");
                }
                rootProjectDir = tmp;
            }

            final BootstrapMavenContextConfig<?> mvnConfig = BootstrapMavenContext.config()
                    .setUserSettings(session.getRequest().getUserSettingsFile())
                    .setRemoteRepositories(repos)
                    .setWorkspaceDiscovery(true)
                    .setPreferPomsFromWorkspace(true)
                    .setCurrentProject(QuarkusBootstrapProvider.getOriginalPomFile(project).toString())
                    .setEffectiveModelBuilder(BootstrapMavenContextConfig.getEffectiveModelBuilderProperty(projectProperties))
                    .setRootProjectDir(rootProjectDir);
            // to support Maven plugins and extensions manipulating POM files
            QuarkusBootstrapProvider.setProvidedModules(mvnConfig, session, toFiles(reloadPoms));

            // There are a couple of reasons we don't want to use the original Maven session:

View on GitHub (pinned to e1c734241f)

Solutions

1. Set maven.top.level.project.basedir to an existing absolute directory of the top-level project.
2. Remove the -Dmaven.top.level.project.basedir property if you do not intentionally need it.
3. Update IDE run configurations or scripts after moving/renaming the project.
4. In containers, ensure the path exists inside the container or map the host directory to the same path via a volume.

Example fix

// before
mvn quarkus:dev -Dmaven.top.level.project.basedir=/home/user/old-project
// after
mvn quarkus:dev -Dmaven.top.level.project.basedir=/home/user/new-project

// validate the system property path before starting dev mode
String dir = System.getProperty("maven.top.level.project.basedir");
if (dir != null && !Files.isDirectory(Path.of(dir))) {
    throw new IllegalStateException("maven.top.level.project.basedir does not exist: " + dir);
}

When it happens

Trigger: Starting dev mode with -Dmaven.top.level.project.basedir=/some/path where the path was deleted, renamed, or is spelled incorrectly, or where a container/CI environment lacks the host-path directory the IDE passed in.

Common situations: Stale IDE run configuration pointing at a moved project folder; Docker/container dev setups forwarding a property with a host path that does not exist inside the container; typo or trailing-slash mismatch in scripts; workspace folder renamed.

Related errors

• Parameter 'mode' was set to '<mode>' while expected one of '
• Dev mode process did not complete successfully
• Failed to run
• Failed to obtain descriptor for Maven plugin <pluginId> goal
• Local dependency <module> does not appear to have any source

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/04d21659c7a76c6b. Report an issue: GitHub.