quarkusio/quarkus · error · RuntimeException

FileName is mandatory, for example 'index.html'

Error message

FileName is mandatory, for example 'index.html'

What it means

Thrown by DevUIContent.Builder.build when a Dev UI extension content contribution is finalized without a file name. The builder pattern lets extension authors register static content for the Dev UI; fileName (e.g. 'index.html') is the mandatory identifier used to serve the contribution, and the guard fires at build time when the developer forgot to call fileName(...) before build().

Source

Thrown at extensions/devui/deployment-spi/src/main/java/io/quarkus/devui/spi/DevUIContent.java:110

        public Builder descriptions(Map<String, String> descriptions) {
            this.descriptions = descriptions;
            return this;
        }

        public Builder mcpDefaultEnables(Map<String, String> mcpDefaultEnabled) {
            this.mcpDefaultEnabled = mcpDefaultEnabled;
            return this;
        }

        public Builder contentTypes(Map<String, String> contentTypes) {
            this.contentTypes = contentTypes;
            return this;
        }

        public DevUIContent build() {
            if (fileName == null) {
                throw new RuntimeException(
                        ERROR + " FileName is mandatory, for example 'index.html'");
            }

            if (template == null) {
                template = DEFAULT_TEMPLATE;
            }

            return new DevUIContent(this);
        }

        private static final String ERROR = "Not enough information to create Dev UI content.";
        private static final byte[] DEFAULT_TEMPLATE = "Here the template of your page. Set your own by providing the template() in the DevUIContent"
                .getBytes();
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Add .fileName("your-page.html") to the builder chain before build()
2. Ensure fileName includes an extension, e.g. index.html

Example fix

// before
DevUIContent.builder()
    .template(templateBytes)
    .build();
// after
DevUIContent.builder()
    .fileName("index.html")
    .template(templateBytes)
    .build();

if (fileName == null || fileName.isBlank()) {
    throw new IllegalArgumentException("DevUIContent fileName is required, e.g. 'index.html'");
}

boolean hasFileName(DevUIContent.Builder b) { return b != null; } // no public accessor; validate the string before passing

try {
    content = builder.build();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("FileName is mandatory")) { /* set fileName and retry */ }
    else throw e;
}

When it happens

Trigger: Calling DevUIContent.builder().template(...).build() without calling fileName(String) first.

Common situations: Copy-pasting a new Dev UI content registration from an example and forgetting the fileName line, or refactoring a builder chain and dropping the call.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid template
• Only one of runtimeValue, function or assistantFunction is a
• methodName must be provided
• Either function, assistantFunction or runtimeValue must be p
• Either function or runtimeValue must be provided

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