quarkusio/quarkus · error · BootstrapMavenException

Top-level project base directory specified with system prop

Error message

Top-level project base directory  specified with system property quarkus.bootstrap.maven-top-level-project-root-dir does not exist

What it means

Thrown as a BootstrapMavenException in the BootstrapMavenContext constructor: when no rootProjectDir was supplied in the config, Quarkus reads the system property quarkus.bootstrap.maven-top-level-project-base-dir; if that property is set but the path does not exist on disk, construction fails immediately.

Source

Thrown at independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/BootstrapMavenContext.java:181

        this.localRepoTail = config.localRepoTail;
        this.localRepoTailIgnoreAvailability = config.localRepoTailIgnoreAvailability;
        this.offline = config.offline;
        this.warnOnFailingWorkspaceModules = config.warnOnFailedWorkspaceModules;
        this.repoSystem = config.repoSystem;
        this.repoSession = config.repoSession;
        this.remoteRepos = config.remoteRepos;
        this.remotePluginRepos = config.remotePluginRepos;
        this.remoteRepoManager = config.remoteRepoManager;
        this.settingsDecrypter = config.settingsDecrypter;
        this.cliOptions = config.cliOptions;
        this.excludeSisuBeanPackages = config.getExcludeSisuBeanPackages();
        this.includeSisuBeanPackages = config.getIncludeSisuBeanPackages();
        if (config.rootProjectDir == null) {
            final String topLevelBaseDirStr = PropertyUtils.getProperty(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 " + MAVEN_TOP_LEVEL_PROJECT_BASEDIR + " does not exist");
                }
                this.rootProjectDir = tmp;
            }
        } else {
            this.rootProjectDir = config.rootProjectDir;
        }
        this.preferPomsFromWorkspace = config.preferPomsFromWorkspace;
        this.effectiveModelBuilder = config.effectiveModelBuilder;
        this.wsModuleParentHierarchy = config.wsModuleParentHierarchy;
        this.userSettings = config.userSettings;
        if (config.currentProject != null) {
            this.currentProject = config.currentProject;
            this.currentPom = currentProject.getRawModel().getPomFile().toPath();
            this.workspace = config.currentProject.getWorkspace();
        } else if (config.workspaceDiscovery) {
            currentProject = resolveCurrentProject(config.providedModules);
            this.workspace = currentProject == null ? null : currentProject.getWorkspace();

View on GitHub (pinned to e1c734241f)

Solutions

Correct the system property value to an existing absolute path
Remove the property if a top-level root dir is not actually needed
Create the directory if it is supposed to exist (e.g. in CI scripts before the build)
In tests/launch configs, derive the path from the module directory rather than hardcoding it

Example fix

// before
-Dquarkus.bootstrap.maven-top-level-project-base-dir=/home/user/old-project
// after
-Dquarkus.bootstrap.maven-top-level-project-base-dir=/home/user/projects/current-project

Defensive patterns

Strategy: validation

Validate before calling

String dir = System.getProperty("quarkus.bootstrap.maven-top-level-project-base-dir");
if (dir != null && !java.nio.file.Files.isDirectory(java.nio.file.Path.of(dir))) {
    throw new IllegalStateException("quarkus.bootstrap.maven-top-level-project-base-dir points to a missing dir: " + dir);
}

Prevention

Always use absolute paths for this property
Set the property programmatically in tests from the project base dir (e.g. MavenProject basedir), never hardcoded
Remove the property when not needed
In CI, export the checkout path once and reference it consistently

When it happens

Trigger: Launching an app/test with -Dquarkus.bootstrap.maven-top-level-project-base-dir=/some/path where /some/path does not exist (typo, relative path resolved from the wrong working dir, path deleted before run, test runner cwd differing from expectation).

Common situations: IDE run configurations passing stale absolute paths; CI checking out to a different directory than the hardcoded property; relative path assumptions broken by Gradle/Maven daemon working directories.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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