alibaba/spring-ai-alibaba · error · RuntimeException

Error processing template: ${templateName}

Error message

Error processing template: ${templateName}

What it means

AgentProjectGenerator.renderAndWriteTemplates() wraps IOException from rendering a template or writing the output file in a RuntimeException with this message. It indicates the template engine failed or the target file could not be written during project generation. The original IOException is chained as the cause.

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/agent/AgentProjectGenerator.java:115

	}

	private void renderAndWriteTemplates(List<String> templateNames, List<Map<String, Object>> models, Path projectRoot,
			ProjectDescription projectDescription) {
		Path fileRoot = createDirectory(projectRoot, projectDescription);

		for (int i = 0; i < templateNames.size(); i++) {
			String templateName = templateNames.get(i);
			Map<String, Object> model = models.get(i);
			Path filePath = fileRoot.resolve(templateName);

			try {
				String template = templateRenderer.render(templateName, model);

				// 覆盖写文件（自动创建/替换文件）
				Files.writeString(filePath, template, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
			}
			catch (IOException e) {
				throw new RuntimeException("Error processing template: " + templateName, e);
			}
		}
	}

	private Path createDirectory(Path projectRoot, ProjectDescription projectDescription) {
		StringBuilder pathBuilder = new StringBuilder("src/main/").append(projectDescription.getLanguage().id());
		String packagePath = projectDescription.getPackageName().replace('.', '/');
		pathBuilder.append("/").append(packagePath).append("/graph/");
		try {
			return Files.createDirectories(projectRoot.resolve(pathBuilder.toString()));
		}
		catch (Exception e) {
			throw new RuntimeException("Got error when creating files", e);
		}
	}

	private CodeSections collectSections(Agent agent, RenderContext ctx) {
		// 递归先处理子 agent，收集子 varNames

View on GitHub (pinned to f82da0b50f)

Solutions

1. Inspect the chained cause (getCause()) for the real IOException — path, permission, or template resolution
2. Verify the output project directory exists, is writable, and has free disk space
3. Confirm all template resources ship in the jar (rebuild/repackage the module)
4. Check the project/package name for characters invalid in file paths

Example fix

null

Path out = Paths.get(outputDir);
if (!Files.isWritable(out) || out.toFile().getUsableSpace() < 10_000_000) {
    throw new IllegalStateException("output directory not writable or low on disk");
}

try {
    generator.generate(description);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Error processing template")) {
        log.error("Template {} failed: {}", e.getMessage(), e.getCause());
    }
}

When it happens

Trigger: During generate(), templateRenderer.render(templateName, model) or Files.writeString(filePath, ...) throws IOException for one of the project's templates.

Common situations: Missing template resource in the packaged jar (build/packaging issue); disk full or read-only target directory; invalid characters in the project name producing an invalid file path; permission problems on the output directory.

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

• WORKFLOW_EXECUTE_ERROR
• Read dsl file failed, please check if the encoding of file i
• Got error when creating files
• Got error when rendering template${templateName}
• Got error when creating files

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