spring-projects/spring-boot · error · RuntimeException

Error packaging archive for image

Error message

Error packaging archive for image

What it means

RuntimeException thrown by PackagedTarArchive.writeTo while converting a packaged jar/war into the tar stream consumed by the image builder. packageImage iterates jar entries and writes each as a TarArchiveEntry via the write helper; any RuntimeException from packaging, entry conversion, or stream writes is caught, the OutputStream is closed, and the cause is re-wrapped for clarity.

Solutions

1. Inspect the wrapped cause — it usually names the specific entry or operation that failed.
2. Re-run `mvn clean package` to regenerate a known-good archive before build-image.
3. Verify the source jar/war opens cleanly (`jar tf target/*.jar`).
4. If using a custom ImagePackager customization, ensure entryWriters are non-null for file entries.

Example fix

// before: mvn spring-boot:build-image   (against a stale/corrupt target/*.jar)
// after:  mvn clean package spring-boot:build-image

// Verify the input archive is well-formed before build-image:
try (JarFile jf = new JarFile(archiveFile)) {
    // iterate a few entries; any exception means a corrupt jar
    Enumeration<JarEntry> e = jf.entries();
    while (e.hasMoreElements()) { jf.getInputStream(e.nextElement()).close(); }
}

try {
    // invoke build-image
} catch (RuntimeException ex) {
    if ("Error packaging archive for image".equals(ex.getMessage())) {
        Throwable cause = ex.getCause(); // the per-entry failure
    }
    throw ex;
}

When it happens

Trigger: A RuntimeException during ImagePackager.packageImage or while writing individual entries (e.g., ZipEntry→TarArchiveEntry conversion failure, null entryWriter on a file entry, duplicate entry, corrupted source archive). Triggered at build-image time.

Common situations: Corrupt or truncated input jar (often from an interrupted previous package); non-standard archive contents the converter can't handle; concurrent writes to the same tar; disk full mid-stream surfacing as an unchecked exception; entry larger than allowed tar limits.

Related errors

• A jar or war file is required for building image
• Invalid Docker configuration, either context or host can be…
• Source file is not available, make sure 'package' runs as…
• Can't parse ' ' to instant
• Could not build classpath

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

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