alibaba/spring-ai-alibaba · error · InvalidProjectRequestException

Unknown dependency '${dep}' check project metadata

Error message

Unknown dependency '${dep}' check project metadata

What it means

validateDependencies() iterates every dependency id in the request and resolves it in the Initializr metadata's dependency catalog. Any unknown id immediately throws InvalidProjectRequestException('Unknown dependency ... check project metadata'). All requested dependencies must be declared in metadata.getDependencies().

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/generator/GraphProjectReqToDescConverter.java:172

		}
	}

	private void validatePackaging(String packaging, InitializrMetadata metadata) {
		if (packaging != null) {
			DefaultMetadataElement packagingFromMetadata = metadata.getPackagings().get(packaging);
			if (packagingFromMetadata == null) {
				throw new InvalidProjectRequestException(
						"Unknown packaging '" + packaging + "' check project metadata");
			}
		}
	}

	private void validateDependencies(ProjectRequest request, InitializrMetadata metadata) {
		List<String> dependencies = request.getDependencies();
		dependencies.forEach((dep) -> {
			Dependency dependency = metadata.getDependencies().get(dep);
			if (dependency == null) {
				throw new InvalidProjectRequestException("Unknown dependency '" + dep + "' check project metadata");
			}
		});
	}

	private void validateDependencyRange(Version platformVersion, List<Dependency> resolvedDependencies) {
		resolvedDependencies.forEach((dep) -> {
			if (!dep.match(platformVersion)) {
				throw new InvalidProjectRequestException(
						"Dependency '" + dep.getId() + "' is not compatible " + "with Spring Boot " + platformVersion);
			}
		});
	}

	private BuildSystem getBuildSystem(ProjectRequest request, InitializrMetadata metadata) {
		Map<String, String> typeTags = metadata.getTypes().get(request.getType()).getTags();
		String id = typeTags.get("build");
		String dialect = typeTags.get("dialect");
		return BuildSystem.forIdAndDialect(id, dialect);

View on GitHub (pinned to f82da0b50f)

Solutions

  1. Fetch the current metadata (dependencies list) from the generator and use only listed dependency ids
  2. Fix typos in dependency ids in the request
  3. Register custom dependencies in the initializr metadata (initializr.dependencies)
  4. Remove stale/renamed dependency ids after an upgrade

Example fix

// before
request.setDependencies(Arrays.asList("web", "spring-ai-alibaba-starter-dashcope-typo"));
// after
request.setDependencies(Arrays.asList("web", "spring-ai-alibaba-starter-dashscope"));
Defensive patterns

Strategy: validation

Validate before calling

Set<String> known = metadata.getDependencies().ids();
List<String> bad = request.getDependencies().stream().filter(d -> !known.contains(d)).toList();
if (!bad.isEmpty()) { throw new IllegalArgumentException("Unknown dependencies: " + bad); }

Try / catch

try {
    converter.validate(request);
} catch (InvalidProjectRequestException e) {
    return ResponseEntity.badRequest().body(e.getMessage());
}

Prevention

When it happens

Trigger: Calling validate/convert with ProjectRequest dependencies containing at least one id absent from metadata.getDependencies().get(dep) — e.g. 'webflux-typo', a removed starter, or a custom dependency the admin metadata never registered.

Common situations: Hand-written dependency ids in scripts, upgrading spring-ai-alibaba where dependency ids were renamed, client cached metadata listing dependencies no longer offered.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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