spring-projects/spring-boot · error · RuntimeException

Error packaging archive for image

Error message

Error packaging archive for image

What it means

Thrown by BuildImageMojo.PackagedTarArchive.writeTo as a RuntimeException wrapping a RuntimeException raised while the ImagePackager lays out the application into the tar stream sent to the builder. This is the boundary where the repackaged archive contents are converted into layered tar entries; any failure in packager.packageImage (entry writer, layout, library handling) is caught, the output stream is closed, and the error is re-thrown with this message. Note it also closes outputStream before re-throwing.

Source

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

		private final ImagePackager packager;

		PackagedTarArchive(Owner owner, Libraries libraries, ImagePackager packager) {
			this.owner = owner;
			this.libraries = libraries;
			this.packager = packager;
		}

		@Override
		public void writeTo(OutputStream outputStream) throws IOException {
			TarArchiveOutputStream tar = new TarArchiveOutputStream(outputStream);
			tar.setLongFileMode(TarArchiveOutputStream.LONGFILE_POSIX);
			try {
				this.packager.packageImage(this.libraries, (entry, entryWriter) -> write(entry, entryWriter, tar));
			}
			catch (RuntimeException ex) {
				outputStream.close();
				throw new RuntimeException("Error packaging archive for image", ex);
			}
		}

		private void write(ZipEntry jarEntry, @Nullable EntryWriter entryWriter, TarArchiveOutputStream tar) {
			try {
				TarArchiveEntry tarEntry = convert(jarEntry);
				tar.putArchiveEntry(tarEntry);
				if (tarEntry.isFile()) {
					Assert.state(entryWriter != null, "'entryWriter' must not be null");
					entryWriter.write(tar);
				}
				tar.closeArchiveEntry();
			}
			catch (IOException ex) {
				throw new IllegalStateException(ex);
			}
		}

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. Run mvn clean package spring-boot:build-image to guarantee a coherent source archive.
2. Inspect the wrapped cause — if it is an IllegalStateException about 'entryWriter', the layout/packaging combination is likely wrong.
3. Remove or simplify any custom <layers> configuration to determine if it is the source of the packaging failure.
4. Ensure the <layout> matches the project packaging (JAR for jar, WAR for war).

Example fix

// before — mismatched layout
<layout>WAR</layout> <!-- on a jar-packaged project -->
// after — let the plugin guess, or match packaging
<layout>JAR</layout>

// If you invoke BuildImage programmatically / in a test
try {
    // trigger build-image packaging
} catch (RuntimeException ex) {
    if (ex.getMessage() != null && ex.getMessage().contains("Error packaging archive for image")) {
        Throwable cause = ex.getCause();
        // inspect cause: entryWriter null -> layout/packaging mismatch
    }
    throw ex;
}

When it happens

Trigger: An EntryWriter returning null for a file entry (caught downstream as IllegalStateException in BuildImageMojo.write, then propagated here); a corrupted or truncated source jar that the ImagePackager cannot read; an IOException during writing that is wrapped into IllegalStateException by the inner write method; incompatible layout vs packaging type.

Common situations: Source archive was partially written by a previous failed build; mixing layout=WAR with a jar packaging; custom layers configuration that produces no layers yet selectors reference content; concurrent build writing to the same target directory.

Related errors

• A jar or war file is required for building image
• Invalid Docker configuration, either context or host can be
• Invalid Docker {} registry configuration, either token or us
• Failed to load layers configuration with name '%s': '%s' not
• Failed to process custom layers configuration {}

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