What causes "can't load template {name}" in OpenAPITools/openapi-generator?

Check the preceding LOGGER.error line — it prints the underlying cause (null reader vs exception) that this message omits.

OpenAPITools/openapi-generator · error · RuntimeException

can't load template {name}

Error message

can't load template {name}

What it means

Terminal failure of TemplateManager.readTemplate(name): either getTemplateReader(name) returned null (wrapped 'no file found') or the Scanner/read threw, both caught and logged, after which this RuntimeException is thrown. The template name passed the traversal guard and possibly produced a resolvable path, but the actual read failed. The original exception is logged (with stack trace) but not attached as the cause of the rethrow.

Source

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

     * @return The raw template contents
     */
    @SuppressWarnings("java:S112")
    // ignored rule java:S112 as RuntimeException is used to match previous exception type
    public String readTemplate(String name) {
        if (name == null || name.contains("..")) {
            throw new IllegalArgumentException("Template location must be constrained to template directory.");
        }
        try (Reader reader = getTemplateReader(name)) {
            if (reader == null) {
                throw new RuntimeException("no file found");
            }
            try (Scanner s = new Scanner(reader).useDelimiter("\\A")) {
                return s.hasNext() ? s.next() : "";
            }
        } catch (Exception e) {
            LOGGER.error("{}", e.getMessage(), e);
        }
        throw new RuntimeException("can't load template " + name);
    }

    @SuppressWarnings({"squid:S2095", "java:S112"})
    // ignored rule squid:S2095 as used in the CLI and it's required to return a reader
    // ignored rule java:S112 as RuntimeException is used to match previous exception type
    public Reader getTemplateReader(String name) {
        try {
            InputStream is = getInputStream(name);
            return new InputStreamReader(is, StandardCharsets.UTF_8);
        } catch (IOException e) {
            LOGGER.error(e.getMessage());
            throw new RuntimeException("can't load template " + name);
        }
    }

    private InputStream getInputStream(String name) throws IOException {
        if (name == null || name.contains("..")) {
            throw new IllegalArgumentException("Template location must be constrained to template directory.");

View on GitHub (pinned to fcec517be3)

Solutions

Check the preceding LOGGER.error line — it prints the underlying cause (null reader vs exception) that this message omits.
Verify file permissions/readability of the template in the -t directory and inside the generator JAR.
Re-download/rebuild the openapi-generator JAR if classpath resources are corrupt.
Ensure the template directory is not being modified concurrently during generation.

Example fix

# before: template dir mounted read-only to another user
--template-dir /opt/tpl   # /opt/tpl/model.mustache mode 600 owned by other user
# after
chmod 644 /opt/tpl/model.mustache  # or chown to the running user

Defensive patterns

Strategy: try-catch

Validate before calling

// Check readability before generation
Path p = Paths.get(templateDir, name);
if (!Files.isReadable(p)) throw new IOException("template not readable: " + p);

Try / catch

try { contents = manager.readTemplate(name); } catch (RuntimeException e) { log.error("template read failed for {}", name, e); /* surface LOGGER.error output — it holds the root cause */ throw e; }

Prevention

Check template file permissions in Docker/CI images.
Keep template directories immutable during builds.
When debugging, read the logged cause line above the rethrow — the wrapper drops the cause.

When it happens

Trigger: Template exists in the template-dir listing but the file is unreadable (permissions), deleted between resolution and read, or the classpath resource lookup returns a URL whose stream cannot be opened; also the intermediate 'no file found' path when no loader yields a reader.

Common situations: Docker images running as non-root with restricted template file permissions; concurrent builds mutating template directories; stale or corrupted generator JARs where resource entries exist but streams fail; NFS/symlink oddities in CI.

Related errors

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