spring-projects/spring-boot · error · MojoExecutionException

Could not build classpath

Error message

Could not build classpath

What it means

Thrown by AbstractRunMojo.addClasspath as a MojoExecutionException wrapping any Exception raised while turning the URL array (classes, resources, dependencies) into the -cp argument for the forked JVM. The URLs themselves are gathered first by getClassPathUrls(); this catch specifically guards the ClassPath.of(...).args(true) conversion step, so the cause typically indicates a malformed URL or a ClassPath formatting failure rather than a dependency-resolution problem.

Source

Thrown at build-plugin/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractRunMojo.java:374

				if (i < this.profiles.length - 1) {
					arg.append(",");
				}
			}
			arguments.getArgs().addFirst(arg.toString());
			logArguments("Active profile", this.profiles);
		}
	}

	private void addClasspath(List<String> args) throws MojoExecutionException {
		try {
			ClassPath classpath = ClassPath.of(getClassPathUrls());
			if (getLog().isDebugEnabled()) {
				getLog().debug("Classpath for forked process: " + classpath);
			}
			args.addAll(classpath.args(true));
		}
		catch (Exception ex) {
			throw new MojoExecutionException("Could not build classpath", ex);
		}
	}

	protected URL[] getClassPathUrls() throws MojoExecutionException {
		try {
			List<URL> urls = new ArrayList<>();
			addAdditionalClasspathLocations(urls);
			addResources(urls);
			addProjectClasses(urls);
			addDependencies(urls);
			return urls.toArray(new URL[0]);
		}
		catch (IOException ex) {
			throw new MojoExecutionException("Unable to build classpath", ex);
		}
	}

	private void addAdditionalClasspathLocations(List<URL> urls) throws MalformedURLException {

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. Run with -X (debug) to see the 'Classpath for forked process:' line and identify the offending element.
2. Verify every entry in spring-boot.run.additional-classpath-elements exists and is a directory or jar.
3. Run mvn clean to remove stale target/ contents that may produce malformed URLs.
4. Inspect the wrapped cause (MalformedURLException, URISyntaxException, etc.) to pinpoint the bad path.

Example fix

// before
mvn spring-boot:run -Dspring-boot.run.additional-classpath-elements=lib/extra
// after — absolute, existing path
mvn spring-boot:run -Dspring-boot.run.additional-classpath-elements=/abs/path/extra.jar

// Validate additional classpath elements before running
import java.io.File;
import java.util.List;

void checkElements(List<String> elements) {
    for (String e : elements) {
        File f = new File(e);
        if (!f.exists()) throw new IllegalArgumentException("Missing classpath element: " + e);
    }
}

When it happens

Trigger: Running spring-boot:run with classpath URLs that contain characters ClassPath cannot encode; an additional classpath element (-Dspring-boot.run.additional-classpath-elements) pointing at a path whose File.toURI().toURL() fails; a corrupt artifact file path on disk that yields an invalid URL when the run mojo assembles the classpath.

Common situations: Passing -Dspring-boot.run.additional-classpath-elements with a relative or non-existent path; running on Windows where path-to-URL conversion is fragile; an artifact whose getFile() returns a path with spaces or special characters; stale target/classes after a partial clean.

Related errors

• Failed to load layers configuration with name '%s': '%s' not
• Unable to build classpath
• Failed to process custom layers configuration {}
• A jar or war file is required for building image
• Failed to generate build-info.properties. {}

AI-assisted analysis of spring-projects/spring-boot@5b2dbdbb8b (2026-08-04). Data as JSON: /data/errors/6941887bf6e6e247.json. Report an issue: GitHub.