quarkusio/quarkus · error · IllegalArgumentException

Invalid identifier found: [id]

Error message

Invalid identifier found: [id]

What it means

EngineImpl.putTemplate(String id, Template) requires the template id to be a valid identifier (Identifiers.isValid). Registering a template under an id containing invalid characters throws this IllegalArgumentException.

Source

Thrown at independent-projects/qute/core/src/main/java/io/quarkus/qute/EngineImpl.java:125

    @Override
    public String mapResult(Object result, Expression expression) {
        String val = null;
        for (ResultMapper mapper : resultMappers) {
            if (mapper.appliesTo(expression.getOrigin(), result)) {
                val = mapper.map(result, expression);
                break;
            }
        }
        if (val == null) {
            val = result.toString();
        }
        return val;
    }

    public Template putTemplate(String id, Template template) {
        if (!Identifiers.isValid(id)) {
            throw new IllegalArgumentException("Invalid identifier found: [" + id + "]");
        }
        return templates.put(id, template);
    }

    public Template getTemplate(String id) {
        return templates.computeIfAbsent(id, this::load);
    }

    @Override
    public boolean isTemplateLoaded(String id) {
        return templates.containsKey(id);
    }

    @Override
    public void clearTemplates() {
        templates.clear();
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Sanitize the id before registration: strip path separators/spaces and ensure it matches valid identifier rules
2. Derive the id from the template path the way the default loader does (e.g. 'items/detail' paths are fine only if Identifiers accepts them — otherwise normalize)
3. Validate with Identifiers.isValid(id) before calling putTemplate

Example fix

// before
engine.putTemplate("reports/2024/q1.html", template); // invalid id
// after
engine.putTemplate("reports_2024_q1", template);

if (!io.quarkus.qute.Identifiers.isValid(id)) {
    throw new IllegalArgumentException("Template id not valid: " + id);
}
engine.putTemplate(id, template);

boolean isValidTemplateId(String id) { return io.quarkus.qute.Identifiers.isValid(id); }

try {
    engine.putTemplate(id, template);
} catch (IllegalArgumentException e) {
    id = id.replaceAll("[^A-Za-z0-9_$]", "_");
    engine.putTemplate(id, template);
}

When it happens

Trigger: Calling putTemplate with an id such as "foo/bar", "my template", or one starting with a digit / containing characters outside the allowed identifier set.

Common situations: Programmatically registering templates keyed by file paths or names with slashes/spaces instead of sanitized template ids; dynamic template registration where ids come from user input.

Related errors

• [prefix] is not a valid iteration metadata prefix. The value
• No params to evaluate
• Invalid template link [${templateLink}] - Expeting a link th
• No suitable template variant found
• An attachment must contain either a file or a raw data

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/f01572d0511b1efa. Report an issue: GitHub.