quarkusio/quarkus · error · IllegalStateException

Failed to locate project dir for

Error message

Failed to locate project dir for

What it means

IDELauncherImpl.launch throws this IllegalStateException when BuildToolHelper.getProjectDir(classesDir) returns null, meaning no project root (pom.xml/gradle files) could be located above the given classes directory. Without a project dir the IDE dev-mode launcher cannot construct a QuarkusBootstrap.

Source

Thrown at independent-projects/bootstrap/core/src/main/java/io/quarkus/bootstrap/IDELauncherImpl.java:39

import io.quarkus.bootstrap.workspace.WorkspaceModule;
import io.quarkus.maven.dependency.ResolvedDependency;

/**
 * IDE entry point.
 * <p>
 * This is launched from the core/launcher module. To avoid any shading issues core/launcher unpacks all its dependencies
 * into the jar file, then uses a custom class loader load them.
 */
public class IDELauncherImpl implements Closeable {

    public static final String FORCE_COLOR_SUPPORT = "io.quarkus.force-color-support";

    public static Closeable launch(Path classesDir, Map<String, Object> context) {
        System.setProperty(FORCE_COLOR_SUPPORT, "true");
        System.setProperty("quarkus.console.basic", "true"); //IDE's don't support raw mode
        final Path projectDir = BuildToolHelper.getProjectDir(classesDir);
        if (projectDir == null) {
            throw new IllegalStateException("Failed to locate project dir for " + classesDir);
        }
        try {
            //todo : proper support for everything
            final QuarkusBootstrap.Builder builder = QuarkusBootstrap.builder()
                    .setBaseClassLoader(IDELauncherImpl.class.getClassLoader())
                    .setIsolateDeployment(true)
                    .setMode(QuarkusBootstrap.Mode.DEV)
                    .setTargetDirectory(classesDir.getParent());
            if (BuildToolHelper.isGradleProject(classesDir)) {
                final ApplicationModel quarkusModel = BuildToolHelper.enableGradleAppModelForDevMode(classesDir);
                context.put(BootstrapConstants.SERIALIZED_APP_MODEL,
                        ApplicationModelSerializer.serializeGradleModel(quarkusModel, false));

                ArtifactSources mainSources = quarkusModel.getApplicationModule().getMainSources();

                PathsCollection applicationRoots = collectOutputDirs(mainSources);
                final Path launchingModulePath = applicationRoots.iterator().next();

View on GitHub (pinned to e1c734241f)

Solutions

  1. Run the app from a classes directory inside the actual Maven/Gradle project
  2. Ensure pom.xml or Gradle build files exist at the project root (they are the markers searched for)
  3. Fix the IDE run configuration's working directory/output path
  4. Rebuild the project in place rather than copying class output elsewhere

Example fix

// before
IDELauncherImpl.launch(Path.of("/tmp/classes"), context);
// after
IDELauncherImpl.launch(Path.of("/home/dev/myapp/target/classes"), context); // project root discoverable upward
Defensive patterns

Strategy: validation

Validate before calling

Path classes = Path.of("/home/dev/myapp/target/classes");
boolean hasProjectRoot = false;
for (Path p = classes; p != null; p = p.getParent()) {
    if (Files.exists(p.resolve("pom.xml")) || Files.exists(p.resolve("build.gradle"))) { hasProjectRoot = true; break; }
}
if (!hasProjectRoot) throw new IllegalStateException("No project dir above " + classes);

Try / catch

try {
    IDELauncherImpl.launch(classesDir, ctx);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to locate project dir")) { /* fix classesDir */ }
}

Prevention

When it happens

Trigger: Calling IDELauncherImpl.launch(classesDir, context) with a classes directory that is not under a Maven or Gradle project root — the traversal up the directory tree finds no build-tool marker file.

Common situations: IDE run configurations pointing at a copied classes directory (e.g. under /tmp), launching after moving the project, or running compiled classes outside their source project entirely.

Related errors

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