quarkusio/quarkus · error · TemplateException

[prefix] is not a valid iteration metadata prefix. The value

Error message

[prefix] is not a valid iteration metadata prefix. The value can only consist of alphanumeric characters and underscores.

What it means

EngineBuilder.iterationMetadataPrefix(String) validates the prefix for loop iteration metadata (e.g. __qmh or alias forms). Only the special constants (none, alias_underscore, alias_qm) or values matching the namespace/alphanumeric-underscore pattern are accepted; otherwise a TemplateException is thrown at build time.

Source

Thrown at independent-projects/qute/core/src/main/java/io/quarkus/qute/EngineBuilder.java:306

     * {@link LoopSectionHelper.Factory} is registered, i.e. before {@link #addDefaultSectionHelpers()} or before
     * {@link #addSectionHelper(SectionHelperFactory)}.
     * <p>
     * A valid prefix consists of alphanumeric characters and underscores.
     * <p>
     * Keep in mind that the prefix must be set before the {@link LoopSectionHelper.Factory} is registered, for example before
     * the {@link #addDefaultSectionHelpers()} method is called. In other words, the {@link LoopSectionHelper.Factory} must be
     * re-registered after the prefix is set.
     *
     * @param prefix
     * @return self
     * @see LoopSectionHelper.Factory
     */
    public EngineBuilder iterationMetadataPrefix(String prefix) {
        if (!LoopSectionHelper.Factory.ITERATION_METADATA_PREFIX_NONE.equals(prefix)
                && !LoopSectionHelper.Factory.ITERATION_METADATA_PREFIX_ALIAS_UNDERSCORE.equals(prefix)
                && !LoopSectionHelper.Factory.ITERATION_METADATA_PREFIX_ALIAS_QM.equals(prefix)
                && !Namespaces.NAMESPACE_PATTERN.matcher(prefix).matches()) {
            throw new TemplateException("[" + prefix
                    + "] is not a valid iteration metadata prefix. The value can only consist of alphanumeric characters and underscores.");
        }
        this.iterationMetadataPrefix = prefix;
        return this;
    }

    /**
     * The global rendering timeout.
     *
     * @param value Timeout in milliseconds
     * @return self
     */
    public EngineBuilder timeout(long value) {
        this.timeout = value;
        return this;
    }

    /**

View on GitHub (pinned to e1c734241f)

Solutions

1. Use one of the accepted constants: "none", "<alias>__", or "<alias>?" (alias itself alphanumeric/underscore)
2. Fix the configured prefix so it contains only alphanumerics and underscores, e.g. `it_`
3. If using the alias forms, check quarkus.qute.iteration-metadata-prefix property value for stray characters

Example fix

// before
quarkus.qute.iteration-metadata-prefix=it-
// after
quarkus.qute.iteration-metadata-prefix=it_

String prefix = config.value;
boolean ok = "none".equals(prefix) || prefix.matches("[A-Za-z0-9_]+");
if (!ok) throw new IllegalArgumentException("Invalid iteration metadata prefix: " + prefix);

When it happens

Trigger: Calling builder.iterationMetadataPrefix(prefix) with an empty string, or one containing characters other than alphanumerics and underscores (e.g. '-', '.', '$').

Common situations: Configuring iteration metadata via application.properties (quarkus.qute.iteration-metadata-prefix) with an invalid value like 'it-' or 'my.prefix', then the EngineProducer passes it to the builder.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Namespace [%s] may not be handled by multiple resolvers of t
• Invalid identifier found: [id]
• No params to evaluate
• Unrecognized dependency flag '<trimmed>'. Supported flags: O
• Parameter 'mode' was set to '<mode>' while expected one of '

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