apache/maven · error · IllegalStateException

Recursive build requested but source has no path

Error message

Recursive build requested but source has no path

What it means

buildBuildPom() implements recursive model building by walking the file system from the request's source up to the root POM (via session.getRootDirectory() / RootLocator.findMandatoryRoot). That walk needs a real Path; ModelSource implementations backed by a URL, a String, or an InputStream return null from getPath(), so the request fails fast with IllegalStateException.

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/model/DefaultModelBuilder.java:817

            properties.putAll(request.getSystemProperties());
            properties.putAll(request.getUserProperties());

            return properties;
        }

        /**
         * Convenience method for getting properties with profiles without additional base properties.
         * This is a backward compatibility method that provides an empty base properties map.
         */
        private Map<String, String> getPropertiesWithProfiles(Model model) {
            return getPropertiesWithProfiles(model, new HashMap<>());
        }

        private void buildBuildPom() throws ModelBuilderException {
            // Retrieve and normalize the source path, ensuring it's non-null and in absolute form
            Path top = request.getSource().getPath();
            if (top == null) {
                throw new IllegalStateException("Recursive build requested but source has no path");
            }
            top = top.toAbsolutePath().normalize();

            // Obtain the root directory, resolving it if necessary
            Path rootDirectory;
            try {
                rootDirectory = session.getRootDirectory();
            } catch (IllegalStateException e) {
                rootDirectory = session.getService(RootLocator.class).findMandatoryRoot(top);
            }

            // Locate and normalize the root POM if it exists, fallback to top otherwise
            Path root = modelProcessor.locateExistingPom(rootDirectory);
            if (root != null) {
                root = root.toAbsolutePath().normalize();
            } else {
                root = top;
            }

View on GitHub (pinned to e4093d4e12)

Solutions

  1. Write the pom to disk (or use the existing file) and pass a path-based Source so getPath() is non-null
  2. Build non-recursively when the model can only come from memory or a URL
  3. Locate the root pom yourself and pass that file's source for the recursive build

Example fix

// before: recursive build from an in-memory model
request.setSource(new StringModelSource(pomXml));
request.setRecursive(true);

// after: recursive build from a real file
Path pom = Path.of(projectDir, "pom.xml");
request.setSource(Sources.buildSource(pom));
request.setRecursive(true);
Defensive patterns

Strategy: validation

Validate before calling

if (request.isRecursive() && request.getSource().getPath() == null) {
    // non-file source cannot drive a recursive build
    throw new IllegalArgumentException(
        "Recursive builds require a file-based ModelSource; got: " + request.getSource().getClass().getName());
}

Try / catch

try {
    result = modelBuilder.build(request);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("source has no path")) {
        // fall back to non-recursive build or write the model to a temp file first
    } else throw e;
}

Prevention

When it happens

Trigger: Requesting a recursive build while the ModelSource is non-file-based: e.g. request.setSource(new StringModelSource(pomXml)) or a URL-based source, which makes request.getSource().getPath() return null inside buildBuildPom().

Common situations: Embedding Maven (maven-embedder, IDE tooling, tests) and handing the builder an in-memory or remote pom; migrating from older APIs where the caller drove recursion from files itself.

Related errors

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