{"record":{"id":"31423d52fefb58d9","repo":"quarkusio/quarkus","slug":"prefix-is-not-a-valid-iteration-metadata-prefix","errorCode":null,"errorMessage":"[prefix] is not a valid iteration metadata prefix. The value can only consist of alphanumeric characters and underscores.","messagePattern":"\\[prefix\\] is not a valid iteration metadata prefix\\. The value can only consist of alphanumeric characters and underscores\\.","errorType":"exception","errorClass":"TemplateException","httpStatus":null,"severity":"error","filePath":"independent-projects/qute/core/src/main/java/io/quarkus/qute/EngineBuilder.java","lineNumber":306,"sourceCode":"     * {@link LoopSectionHelper.Factory} is registered, i.e. before {@link #addDefaultSectionHelpers()} or before\n     * {@link #addSectionHelper(SectionHelperFactory)}.\n     * <p>\n     * A valid prefix consists of alphanumeric characters and underscores.\n     * <p>\n     * Keep in mind that the prefix must be set before the {@link LoopSectionHelper.Factory} is registered, for example before\n     * the {@link #addDefaultSectionHelpers()} method is called. In other words, the {@link LoopSectionHelper.Factory} must be\n     * re-registered after the prefix is set.\n     *\n     * @param prefix\n     * @return self\n     * @see LoopSectionHelper.Factory\n     */\n    public EngineBuilder iterationMetadataPrefix(String prefix) {\n        if (!LoopSectionHelper.Factory.ITERATION_METADATA_PREFIX_NONE.equals(prefix)\n                && !LoopSectionHelper.Factory.ITERATION_METADATA_PREFIX_ALIAS_UNDERSCORE.equals(prefix)\n                && !LoopSectionHelper.Factory.ITERATION_METADATA_PREFIX_ALIAS_QM.equals(prefix)\n                && !Namespaces.NAMESPACE_PATTERN.matcher(prefix).matches()) {\n            throw new TemplateException(\"[\" + prefix\n                    + \"] is not a valid iteration metadata prefix. The value can only consist of alphanumeric characters and underscores.\");\n        }\n        this.iterationMetadataPrefix = prefix;\n        return this;\n    }\n\n    /**\n     * The global rendering timeout.\n     *\n     * @param value Timeout in milliseconds\n     * @return self\n     */\n    public EngineBuilder timeout(long value) {\n        this.timeout = value;\n        return this;\n    }\n\n    /**","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/qute/core/src/main/java/io/quarkus/qute/EngineBuilder.java#L288-L324","documentation":"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.","triggerScenarios":"Calling builder.iterationMetadataPrefix(prefix) with an empty string, or one containing characters other than alphanumerics and underscores (e.g. '-', '.', '$').","commonSituations":"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.","solutions":["Use one of the accepted constants: \"none\", \"<alias>__\", or \"<alias>?\" (alias itself alphanumeric/underscore)","Fix the configured prefix so it contains only alphanumerics and underscores, e.g. `it_`","If using the alias forms, check quarkus.qute.iteration-metadata-prefix property value for stray characters"],"exampleFix":"// before\nquarkus.qute.iteration-metadata-prefix=it-\n// after\nquarkus.qute.iteration-metadata-prefix=it_","handlingStrategy":"validation","validationCode":"String prefix = config.value;\nboolean ok = \"none\".equals(prefix) || prefix.matches(\"[A-Za-z0-9_]+\");\nif (!ok) throw new IllegalArgumentException(\"Invalid iteration metadata prefix: \" + prefix);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use documented values: none, <alias>__, <alias>? ","Validate quarkus.qute.iteration-metadata-prefix values in CI config checks","Keep prefixes alphanumeric/underscore only","Copy-paste accepted constants instead of typing new ones"],"tags":["qute","templates","configuration","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}