alibaba/spring-ai-alibaba · error · RuntimeException

Error processing template

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.

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

• Code must not be null
• Code must not be null
• 搜索请求执行失败
• 批量索引失败
• Failed to clear file system store

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

Appendix: 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)