spring-projects/spring-boot · error · MojoExecutionException

Could not build classpath

Error message

Could not build classpath

What it means

MojoExecutionException thrown by AbstractRunMojo.addClasspath when ANY exception escapes ClassPath.of(getClassPathUrls()) or the subsequent args(true) call. The method deliberately catches a broad Exception because the classpath assembly for the forked process can fail in many ways (URL construction, dependency resolution, resource scanning). The original exception is chained as the cause.

Solutions

1. Inspect the chained cause (ex) — it identifies which sub-step (additional classpath, resources, classes, or dependencies) failed.
2. Run with -X (debug) to see the logged 'Classpath for forked process' attempt and the failing URL.
3. Validate every <additionalClasspathElements> value as a real filesystem path.
4. Run `mvn dependency:tree` to confirm all compile/runtime dependencies resolve, then re-run spring-boot:run.

Example fix

// before: <additionalClasspathElements><additionalClasspathElement>/opt/lib:bad|path</additionalClasspathElement></additionalClasspathElements>
// after:  <additionalClasspathElements><additionalClasspathElement>/opt/lib/good-path.jar</additionalClasspathElement></additionalClasspathElements>

// Sanity-check additionalClasspathElements before running spring-boot:run:
for (String e : additionalClasspathElements) {
    if (e == null || e.isEmpty() || !new File(e).exists()) {
        throw new IllegalArgumentException("Bad additionalClasspathElement: " + e);
    }
}

try {
    // invoke run/forked goal
} catch (MojoExecutionException ex) {
    if ("Could not build classpath".equals(ex.getMessage())) {
        Throwable c = ex.getCause(); // the actual URL/path failure
    }
    throw ex;
}

When it happens

Trigger: Running `spring-boot:run` (or any forked run) where getClassPathUrls() throws (MalformedURLException from addAdditionalClasspathLocations/addResources/addDependencies), or ClassPath.of rejects the URL array, or args(true) fails.

Common situations: Badly formed <additionalClasspathElements> entry (not a valid path/URL); a dependency JAR is missing from the local repo; resources directory points to a non-existent location; version mismatch leaving a dependency unresolved; running on a JDK that rejects a constructed URL.

Related errors

• Unable to build classpath
• Failed to load layers configuration with name
• Unable to find ' ' dependency. Please ensure JUnit is…
• Unable to load layers XSD
• A jar or war file is required for building image

AI-assisted analysis of spring-projects/spring-boot@270dfe353f (2026-08-11). Data as JSON: /api/errors/6941887bf6e6e247. Report an issue: GitHub.

Appendix: source

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

				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 270dfe353f)