alibaba/spring-ai-alibaba · error · RuntimeException

Failed to copy JAR files to working directory

Error message

Failed to copy JAR files to working directory

What it means

Thrown by FileUtils.copyResourceJarToWorkDir when any step of opening the resource JAR's filesystem, walking its /lib directory, or copying nested JARs into the working directory fails. It wraps the original exception (IOException, FileSystemNotFoundException, ProviderNotFoundException, etc.), so the cause chain is essential for diagnosis.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-builtin-nodes/src/main/java/com/alibaba/cloud/ai/graph/utils/FileUtils.java:121

				if ("file".equals(libUrl.getProtocol())) {
					copyJarFilesFromDir(Path.of(libUrl.toURI()), targetDir);
					continue;
				}
				if ("jar".equals(libUrl.getProtocol())) {
					String jarUrl = libUrl.toString();
					int separatorIndex = jarUrl.indexOf("!/");
					if (separatorIndex <= 0) {
						continue;
					}
					URI jarFileUri = URI.create(jarUrl.substring(0, separatorIndex));
					try (FileSystem fs = FileSystems.newFileSystem(jarFileUri, Collections.emptyMap())) {
						copyJarFilesFromDir(fs.getPath("/lib"), targetDir);
					}
				}
			}
		}
		catch (Exception e) {
			throw new RuntimeException("Failed to copy JAR files to working directory", e);
		}
	}

	/**
	 * Copies all JAR files under the source directory to the target directory.
	 * @param sourceDir The source directory containing JAR files.
	 * @param targetDir The target directory where JAR files will be copied.
	 * @throws IOException if I/O operations fail while scanning or copying files.
	 */
	private static void copyJarFilesFromDir(Path sourceDir, Path targetDir) throws IOException {
		if (!Files.exists(sourceDir)) {
			return;
		}
		try (var stream = Files.walk(sourceDir)) {
			stream.filter(path -> path.toString().endsWith(".jar")).forEach(jarPath -> {
				try {
					Path targetPath = targetDir.resolve(jarPath.getFileName().toString());
					Files.copy(jarPath, targetPath, StandardCopyOption.REPLACE_EXISTING);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check the wrapped cause in the stack trace (IOException vs FileSystemNotFoundException) to identify the real failure.
2. Verify the resource JAR exists on the classpath and the path passed is correct.
3. Ensure the working directory exists and the process has write permission to it.
4. If running from a fat/nested JAR, extract the resource JAR to disk first or use an input-stream based copy instead of a zip FileSystem.

Example fix

// before: relying on zipfs for a nested-jar resource
Path jarFsPath = fs.getPath("/lib");
copyJarFilesFromDir(jarFsPath, targetDir);
// after: pre-flight validation of target dir and cause logging
targetDir = Files.createDirectories(targetDir);
try {
    copyJarFilesFromDir(jarFsPath, targetDir);
} catch (RuntimeException e) {
    logger.error("JAR copy failed; targetDir={}, cause={}", targetDir, e.getCause(), e);
    throw e;
}

Path targetDir = Path.of(workDir);
if (!Files.isDirectory(targetDir)) Files.createDirectories(targetDir);
if (!Files.isWritable(targetDir)) throw new IllegalStateException("Work dir not writable: " + targetDir);

try {
    FileUtils.copyResourceJarToWorkDir();
} catch (RuntimeException e) {
    logger.error("JAR copy failed: {}", e.getCause() != null ? e.getCause().toString() : e.getMessage(), e);
}

When it happens

Trigger: Calling copyResourceJarToWorkDir with a resource location that cannot be opened as a zip/JAR filesystem (resource missing, classpath loaded via nested JAR without an unzip-capable FileSystemProvider, or target directory not writable).

Common situations: Running from a Spring Boot fat JAR where the resource JAR is nested inside another JAR; read-only filesystem or container without write permissions to the work dir; resource path typo in classpath configuration.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Failed to copy JAR files to working directory
• Got error when creating files
• Got error when creating files
• Failed to create temp directory for converter
• SKILL.md not found at: {}

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/a86c73faee9d8e1c. Report an issue: GitHub.