spring-projects/spring-boot · error · IllegalStateException

A jar or war file is required for building image

Error message

A jar or war file is required for building image

What it means

Thrown by BuildImageMojo.getArchiveFile as an IllegalStateException when neither the expected target archive (target/<finalName>.<ext>) nor the source artifact file exists. spring-boot:build-image packages an existing jar/war into an OCI image, so it requires the artifact to have been built first. The code deliberately avoids project.getArtifact().getFile() because package may run in a forked lifecycle, so it falls back to the source artifact — if both are absent, the build cannot proceed.

Source

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

			image.setImagePlatform(this.imagePlatform);
		}
		return customize(image.getBuildRequest(this.project.getArtifact(), content));
	}

	private TarArchive getApplicationContent(Owner owner, Libraries libraries, ImagePackager imagePackager) {
		ImagePackager packager = getConfiguredPackager(() -> imagePackager);
		return new PackagedTarArchive(owner, libraries, packager);
	}

	private File getArchiveFile() {
		// We can't use 'project.getArtifact().getFile()' because package can be done in a
		// forked lifecycle and will be null
		File archiveFile = getTargetFile(this.finalName, this.classifier, this.sourceDirectory);
		if (!archiveFile.exists()) {
			archiveFile = getSourceArtifact(this.classifier).getFile();
		}
		if (!archiveFile.exists()) {
			throw new IllegalStateException("A jar or war file is required for building image");
		}
		return archiveFile;
	}

	/**
	 * Return the {@link File} to use to back up the original source.
	 * @return the file to use to back up the original source
	 */
	private @Nullable File getBackupFile() {
		// We can't use 'project.getAttachedArtifacts()' because package can be done in a
		// forked lifecycle and will be null
		if (this.classifier != null) {
			File backupFile = getTargetFile(this.finalName, null, this.sourceDirectory);
			if (backupFile.exists()) {
				return backupFile;
			}
			Artifact source = getSourceArtifact(null);
			if (!this.classifier.equals(source.getClassifier())) {

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. Always run package before build-image: `mvn package spring-boot:build-image`.
2. Bind spring-boot:build-image to the package phase or later in the <executions> block.
3. If using a classifier, confirm the repackaged artifact with that classifier exists under target/.
4. Run mvn clean package spring-boot:build-image to ensure a fresh, complete artifact.

Example fix

// before
mvn spring-boot:build-image
// after
mvn package spring-boot:build-image

// Confirm the archive exists before invoking build-image
import java.io.File;

File target = new File(projectBuildDir, finalName + "." + extension);
if (!target.exists()) {
    throw new IllegalStateException("Run `mvn package` first; missing: " + target);
}

When it happens

Trigger: Invoking spring-boot:build-image directly without first running package; running build-image in a phase before package; configuring a classifier whose repackaged artifact has not been produced; a multi-module reactor where the application module's package step was skipped or failed silently.

Common situations: Running `mvn spring-boot:build-image` instead of `mvn package spring-boot:build-image`; binding build-image to a phase earlier than package; using a <classifier> that doesn't match any produced artifact; clean having removed target/ before build-image runs standalone.

Related errors

• Invalid Docker configuration, either context or host can be
• Source file is not available, make sure 'package' runs as pa
• Failed to load layers configuration with name '%s': '%s' not
• Failed to process custom layers configuration {}
• Could not build classpath

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