quarkusio/quarkus · error · java.lang.IllegalStateException

#cache cannot be used without the 'quarkus-cache' extension

Error message

#cache cannot be used without the 'quarkus-cache' extension

What it means

When the quarkus-cache extension is absent, Qute registers a placeholder #cache section helper whose getValue always throws this IllegalStateException. This fails fast when a template uses {#cache} but no cache implementation is available at runtime.

Source

Thrown at extensions/qute/runtime/src/main/java/io/quarkus/qute/runtime/cache/MissingCacheConfigurator.java:19

package io.quarkus.qute.runtime.cache;

import java.util.concurrent.CompletionStage;
import java.util.function.Function;

import jakarta.enterprise.event.Observes;

import io.quarkus.qute.CacheSectionHelper;
import io.quarkus.qute.EngineBuilder;
import io.quarkus.qute.ResultNode;

public class MissingCacheConfigurator {

    void configureEngine(@Observes EngineBuilder builder) {
        builder.addSectionHelper(new CacheSectionHelper.Factory(new CacheSectionHelper.Cache() {

            @Override
            public CompletionStage<ResultNode> getValue(String key, Function<String, CompletionStage<ResultNode>> loader) {
                throw new IllegalStateException("#cache cannot be used without the 'quarkus-cache' extension");
            }
        }));
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

Add the quarkus-cache extension: io.quarkus:quarkus-cache.
Remove the {#cache} section from the template if caching is not needed.
Guard template sharing so cached fragments are only used in apps with quarkus-cache.

Example fix

// before (pom.xml): no cache extension
// after
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-cache</artifactId>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

boolean hasCache = Class.forName("io.quarkus.cache.CacheManager", false, getClass().getClassLoader()) != null;
if (!hasCache && templateUsesCacheSection) throw new IllegalStateException("Add quarkus-cache for {#cache}");

Try / catch

try { render(template); } catch (IllegalStateException e) { if (e.getMessage().contains("quarkus-cache")) { /* add dependency or drop {#cache} */ } else throw e; }

Prevention

Add io.quarkus:quarkus-cache whenever templates use {#cache}
Document the extension requirement in shared template libraries
Run a startup test that renders cached templates

When it happens

Trigger: Rendering a template containing a {#cache} section while the application does not include the quarkus-cache dependency.

Common situations: Copying templates that use {#cache} into a project without quarkus-cache; the cache extension was removed during dependency cleanup; conditional usage of #cache in a shared template library.

Related errors

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