alibaba/spring-ai-alibaba · error · IllegalArgumentException

Cannot convert resource to file system path: {}

Error message

Cannot convert resource to file system path: {}

What it means

The builder's userSkillsDirectory(Resource) method resolves the Spring Resource to an absolute filesystem path via resource.getFile(); if the resource cannot be converted (e.g. it is not file-backed, like a jar/classpath resource without a file), the thrown IOException is wrapped in IllegalArgumentException.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/skills/registry/filesystem/FileSystemSkillRegistry.java:362

		/**
		 * Sets the user skills directory from a Spring Resource.
		 * <p><b>Optional</b>: If not set, defaults to <code>~/saa/skills</code>
		 * <p>The Resource will be converted to a file system path. If the resource cannot be
		 * resolved to a file (e.g., it's inside a JAR), an IllegalArgumentException will be thrown.
		 *
		 * @param resource the Resource pointing to the user-level skills directory
		 * @return this builder
		 * @throws IllegalArgumentException if the resource cannot be converted to a file system path
		 */
		public Builder userSkillsDirectory(Resource resource) {
			try {
				if (resource != null && resource.exists()) {
					File file = resource.getFile();
					this.userSkillsDirectory = file.getAbsolutePath();
				}
			}
			catch (IOException e) {
				throw new IllegalArgumentException("Cannot convert resource to file system path: " + resource, e);
			}
			return this;
		}

		/**
		 * Sets the project skills directory path.
		 * <p><b>Optional</b>: If not set, defaults to <code>./skills</code>
		 * (current working directory with "skills" subdirectory).
		 *
		 * @param directory the directory path for project-level skills
		 * @return this builder
		 */
		public Builder projectSkillsDirectory(String directory) {
			this.projectSkillsDirectory = directory;
			return this;
		}

		/**

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure skills live in an exploded directory on the filesystem, not inside a JAR
2. Use a Resource that is file-backed (FileSystemResource or an exploded classpath folder)
3. Catch IllegalArgumentException and fall back to a directory path String overload

Example fix

// before
registry.builder().userSkillsDirectory(new ClassPathResource("skills/"));
// after
Path dir = Path.of("config/skills");
registry.builder().userSkillsDirectory(dir.toString());

Resource r = new ClassPathResource("skills/"); if (!"file".equals(r.getURL().getProtocol())) { /* not file-backed; use a path instead */ }

boolean isFileBacked(Resource r) throws IOException { return r.getFile().isDirectory(); }

try { builder.userSkillsDirectory(resource); } catch (IllegalArgumentException e) { builder.userSkillsDirectory(extractedDirPath); }

When it happens

Trigger: Passing a ClassPathResource pointing inside a packaged JAR, a resource from a remote/protocol handler, or any Resource whose getFile() throws IOException because no physical file backs it.

Common situations: Packaging skills as resources inside a Spring Boot fat JAR and then calling userSkillsDirectory(resource) — jar-embedded resources have no File representation; using a wrong resource URL prefix.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot convert resource to file system path:
• Cannot convert resource to file system path: {}
• Got error when creating files
• Dataset version not found: {}
• Invalid experiment status: {}

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