OpenAPITools/openapi-generator · error · RuntimeException

Couldn't load template engine adapter %s. Available options:

Error message

Couldn't load template engine adapter %s. Available options: %n%s

What it means

TemplatingEngineLoader resolves a templating engine by id: it iterates ServiceLoader-registered TemplatingEngineAdapter instances (bundled: handlebars, mustache) and, failing a match, attempts Class.forName(id) as a fallback for user-supplied adapter classes. If neither works it throws RuntimeException listing the available engine ids. The id comes from the templating engine setting (CLI --templating-engine / GeneratorSettings / 'templatingEngine' additional property).

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/TemplatingEngineLoader.java:45

    }

    @SuppressWarnings("java:S112") // ignore java:S112 as generic RuntimeException is acceptable here
    public static TemplatingEngineAdapter byIdentifier(String id) {
        ServiceLoader<TemplatingEngineAdapter> loader = ServiceLoader.load(TemplatingEngineAdapter.class, TemplatingEngineLoader.class.getClassLoader());

        StringBuilder sb = new StringBuilder();
        for (TemplatingEngineAdapter templatingEngineAdapter : loader) {
            if (id.equals(templatingEngineAdapter.getIdentifier())) {
                return templatingEngineAdapter;
            }
            sb.append(templatingEngineAdapter.getIdentifier()).append("\n");
        }

        try {
            // Attempt to load skipping SPI
            return (TemplatingEngineAdapter) Class.forName(id).getDeclaredConstructor().newInstance();
        } catch (Exception e) {
            throw new RuntimeException(String.format(Locale.ROOT, "Couldn't load template engine adapter %s. Available options: %n%s", id, sb), e);
        }
    }
}

View on GitHub (pinned to fcec517be3)

Solutions

1. Use one of the ids printed in the message's 'Available options' list — typically 'handlebars' or 'mustache'.
2. For a custom adapter, give its fully qualified class name and ensure its JAR (with META-INF/services registration) is on the classpath.
3. Check for stray whitespace/case in the --templating-engine value.
4. Omit the option to use the generator's default engine.

Example fix

# before
--templating-engine handlebar
# after
--templating-engine handlebars

Set<String> KNOWN_ENGINES = Set.of("handlebars", "mustache");
if (!KNOWN_ENGINES.contains(engineId) && !isValidClassName(engineId)) {
    throw new IllegalArgumentException("Unknown templating engine: " + engineId + "; valid: " + KNOWN_ENGINES);
}

Catch RuntimeException at startup; if the message starts with "Couldn't load template engine adapter", print the embedded 'Available options' list to the operator.

When it happens

Trigger: --templating-engine handlebar (typo for handlebars); --templating-engine mustache on an installation where the mustache adapter module is absent; passing a fully-qualified custom adapter class name whose JAR is not on the classpath.

Common situations: Typos in CI generator invocations; custom templating adapters built against an older SPI not registered via META-INF/services; trimmed classpaths (gradle module-hell) dropping the adapter module.

Related errors

• %s Input: `%s`. Error: %s
• filter with no value not supported :[{filter}]
• inputSpecFiles list is empty — nothing to merge
• Malformed OpenAPI version '%s' in a source spec. Expected ex
• %s is an invalid enum property naming option. Please choose

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