OpenAPITools/openapi-generator · error · TemplateNotFoundException

{name}

Error message

{name}

What it means

TemplateManager.getFullTemplateFile() asks every configured template loader for a full path for the template name; if all return null it throws TemplateNotFoundException. This means neither the classpath bundles nor the user-supplied template directory (-t/--template-dir) contain a file with that name. It typically surfaces when a generator or user requests a template that was never shipped or whose custom copy is misnamed.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/TemplateManager.java:66

     */
    public TemplateManager(
            TemplateManagerOptions options,
            TemplatingEngineAdapter engineAdapter,
            TemplatePathLocator[] templateLoaders) {
        this.options = options;
        this.engineAdapter = engineAdapter;
        this.templateLoaders = templateLoaders;
    }

    private String getFullTemplateFile(String name) {
        String template = Arrays.stream(this.templateLoaders)
                .map(i -> i.getFullTemplatePath(name))
                .filter(Objects::nonNull)
                .findFirst()
                .orElse("");

        if (StringUtils.isEmpty(template)) {
            throw new TemplateNotFoundException(name);
        }

        if (name == null || name.contains("..")) {
            throw new IllegalArgumentException("Template location must be constrained to template directory.");
        }

        return template;
    }

    /**
     * returns the template content by name
     *
     * @param name the template name (e.g. model.mustache)
     * @return the contents of that template
     */
    @Override
    public String getFullTemplateContents(String name) {
        String fullPath = getFullTemplateFile(name);

View on GitHub (pinned to fcec517be3)

Solutions

1. Verify the exact template filename the generator requests (enable debug logging on TemplateManager) and create/rename the file in your template directory to match.
2. Point -t at the directory that actually contains the template and confirm the path is correct.
3. If using a custom generator, ensure its template resources are packaged and on the classpath.
4. Check filename case on Linux/macOS builds — mismatches that worked on Windows fail elsewhere.

Example fix

# before
--template-dir ./tpl   # ./tpl only contains api.mustache, generator also needs model.mustache elsewhere
# after
# copy the generator's default templates into ./tpl first, then override:
cp -r modules/openapi-generator/src/main/resources/<lang>/ ./tpl/
--template-dir ./tpl

// Ensure required templates exist before invoking generation
String[] required = {"model.mustache", "api.mustache"};
for (String t : required) {
    if (!Files.exists(Paths.get(templateDir, t))
            && getClass().getClassLoader().getResource("templates/" + t) == null) {
        throw new FileNotFoundException("Missing template: " + t);
    }
}

Catch TemplateNotFoundException specifically; distinguish it from other generation failures and report as a template-packaging problem (no retry).

When it happens

Trigger: Running with --template-dir myTemplates where a generator expects e.g. model.mustache/modelDoc.mustache but the directory only overrides some templates without the base library ones (classpath usually covers those, so in practice this fires for templates the classpath also lacks, e.g. a custom generator's private template name); requesting a renamed template via additional properties; case-sensitivity mismatch on case-sensitive filesystems.

Common situations: Custom generator JARs whose templates are not on the classpath; template directories copied from a different generator (Go templates used for a Java generator); filename typos like modelTemplate.mustache vs model.mustache; upgrading generators where a template was renamed.

Related errors

• can't load template {name}
• Could not process model '{name}'.Please make sure that your
• Could not generate model '{modelName}'
• Could not generate api file for '{tag}'
• Could not generate supporting file '{support}'

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/64f9be91fd436b1a. Report an issue: GitHub.