alibaba/spring-ai-alibaba · error · RuntimeException

Failed to copy JAR file: <jarPath>

Error message

Failed to copy JAR file: <jarPath>

What it means

Thrown inside FileUtils.copyJarFilesFromDir for each individual JAR file whose copy to the target directory fails with an IOException. The message includes the source path of the failing JAR; note it is thrown from a stream's forEach, aborting the whole copy operation on the first failure.

Source

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

	/**
	 * 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);
				}
				catch (IOException e) {
					throw new RuntimeException("Failed to copy JAR file: " + jarPath, e);
				}
			});
		}
	}

	/**
	 * Deletes all JAR files from the specified working directory.
	 * @param workDir The working directory from which the JAR files will be deleted.
	 */
	public static void deleteResourceJarFromWorkDir(String workDir) {
		try {
			Path workDirPath = Path.of(workDir);
			if (Files.exists(workDirPath)) {
				try (var stream = Files.walk(workDirPath)) {
					stream.filter(path -> path.toString().endsWith(".jar")).forEach(jarPath -> {
						try {
							Files.deleteIfExists(jarPath);
						}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check the wrapped IOException for the specific OS-level reason (access denied, no space, file in use).
2. Verify write permission and free space on the target directory.
3. Ensure no other process is locking or deleting the JARs while the copy runs.
4. Retry after cleaning the working directory via deleteResourceJarFromWorkDir.

Example fix

// before
Files.copy(jarPath, targetPath, StandardCopyOption.REPLACE_EXISTING);
// after: ensure target dir exists and is writable before the loop
Files.createDirectories(targetDir);
if (!Files.isWritable(targetDir)) {
    throw new IOException("Target dir not writable: " + targetDir);
}
Files.copy(jarPath, targetPath, StandardCopyOption.REPLACE_EXISTING);

if (!Files.isWritable(targetDir)) throw new IllegalStateException("Target dir not writable: " + targetDir);
if (targetDir.toFile().getUsableSpace() < 64L * 1024 * 1024) throw new IllegalStateException("Low disk space");

try {
    FileUtils.copyResourceJarToWorkDir();
} catch (RuntimeException e) {
    if (e.getCause() instanceof IOException io) {
        logger.error("Copy failed for a JAR: {}", io.getMessage(), io);
        Files.createDirectories(targetDir); // then retry once
        FileUtils.copyResourceJarToWorkDir();
    }
}

When it happens

Trigger: Files.copy(jarPath, targetPath, REPLACE_EXISTING) throws IOException — typically because the source JAR disappeared during the walk, the target directory is not writable, or disk is full.

Common situations: Concurrent processes deleting/modifying JARs while walking; read-only or quota-exceeded target disk; antivirus/OS locking the target file on Windows.

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

• Got error when creating files
• Got error when creating files
• Failed to create temp directory for converter
• SKILL.md not found at: {}
• Failed to store item to file system

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