{"record":{"id":"fab427e3e3f9fe9e","repo":"apache/maven","slug":"unable-to-find-the-root-directory-create-a-mvn-d","errorCode":null,"errorMessage":"Unable to find the root directory. Create a .mvn directory in the root directory or add the root=\"true\" attribute on the root project's model to identify it.","messagePattern":"Unable to find the root directory\\. Create a \\.mvn directory in the root directory or add the root=\"true\" attribute on the root project's model to identify it\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"compat/maven-model-builder/src/main/java/org/apache/maven/model/root/RootLocator.java","lineNumber":51,"sourceCode":" *\n * The default implementation will look for a {@code .mvn} child directory\n * or a {@code pom.xml} containing the {@code root=\"true\"} attribute.\n *\n * @see DefaultRootLocator\n * @deprecated use {@code org.apache.maven.api.services.model.RootLocator} instead\n */\n@Deprecated(since = \"4.0.0\")\npublic interface RootLocator {\n\n    String UNABLE_TO_FIND_ROOT_PROJECT_MESSAGE = \"Unable to find the root directory. \"\n            + \"Create a .mvn directory in the root directory or add the root=\\\"true\\\"\"\n            + \" attribute on the root project's model to identify it.\";\n\n    @Nonnull\n    default Path findMandatoryRoot(Path basedir) {\n        Path rootDirectory = findRoot(basedir);\n        if (rootDirectory == null) {\n            throw new IllegalStateException(getNoRootMessage());\n        }\n        return rootDirectory;\n    }\n\n    @Nullable\n    default Path findRoot(Path basedir) {\n        Path rootDirectory = basedir;\n        while (rootDirectory != null && !isRootDirectory(rootDirectory)) {\n            rootDirectory = rootDirectory.getParent();\n        }\n        return rootDirectory;\n    }\n\n    @Nonnull\n    default String getNoRootMessage() {\n        return UNABLE_TO_FIND_ROOT_PROJECT_MESSAGE;\n    }\n","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-model-builder/src/main/java/org/apache/maven/model/root/RootLocator.java#L33-L69","documentation":"RootLocator walks up from a directory looking for the project root: a directory containing .mvn or a model carrying root=\"true\". findMandatoryRoot throws IllegalStateException (this message, also the UNABLE_TO_FIND_ROOT_PROJECT_MESSAGE constant) when no ancestor up to the filesystem root qualifies.","triggerScenarios":"Calling findMandatoryRoot(basedir) directly or via tooling that requires a session root directory (MavenSession.getRootDirectory and friends) on a tree that has no .mvn directory and no root=\"true\" model anywhere above basedir.","commonSituations":"Running root-aware tooling on a bare directory; zip/tar exports that dropped dotfiles including .mvn; CI checkouts with dotfile exclusion rules; multi-module trees where .mvn was never committed.","solutions":["Create a .mvn directory in the project root: mkdir -p /path/to/project/.mvn (an empty one is enough)","Or mark the root model (model 4.0.0+): <project root=\"true\">","Run the build from inside the project tree so basedir is below the root","Customize detection by implementing RootLocator.isRootDirectory/getNoRootMessage instead of suppressing the exception"],"exampleFix":"# before: no marker anywhere above the build directory\nmvn -f /tmp/checkout/module-a/pom.xml verify\n\n# after: mark the root once (either works)\nmkdir -p /tmp/checkout/.mvn\n# or, with model 4.0.0+:\n#   <project root=\"true\"> in /tmp/checkout/pom.xml","handlingStrategy":"validation","validationCode":"// Check for a root before calling the mandatory variant\nPath root = locator.findRoot(basedir);\nif (root == null) {\n    throw new IllegalStateException(\n        \"No .mvn directory above \" + basedir + \"; create it or set root=\\\"true\\\" on the root model\");\n}\nPath mandatory = locator.findMandatoryRoot(basedir);","typeGuard":"static boolean isProjectRoot(Path dir) {\n    return Files.isDirectory(dir.resolve(\".mvn\"));\n}","tryCatchPattern":null,"preventionTips":["Commit an empty .mvn directory (with a .gitkeep) so checkouts keep the root marker","For model 4.0.0+ projects, set root=\"true\" on the root model","When findRoot returns null, fail CI with guidance instead of letting downstream tooling crash"],"tags":["maven","project-root","mvn-directory","workspace-detection"],"backgroundTag":"missing-project-root-marker","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}