quarkusio/quarkus · error · IllegalArgumentException

GeneratedStaticResourceBuildItem endpoint must start with '/

Error message

GeneratedStaticResourceBuildItem endpoint must start with '/': <endpoint>

What it means

GeneratedStaticResourceBuildItem's constructor validates that the endpoint path is absolute; an endpoint not starting with '/' is rejected with this IllegalArgumentException at build time. Endpoints are HTTP paths, so a leading slash is mandatory.

Source

Thrown at extensions/vertx-http/deployment-spi/src/main/java/io/quarkus/vertx/http/deployment/spi/GeneratedStaticResourceBuildItem.java:33

 * file on disk.
 * <br>
 * Behind the scenes the build step will take care of add those resources to the final build, through
 * {@link AdditionalStaticResourceBuildItem}, {@link NativeImageResourceBuildItem}
 * and {@link io.quarkus.deployment.builditem.GeneratedResourceBuildItem} build items.
 * <br>
 * The value of {@code endpoint} should be prefixed with {@code '/'} and reference a file (no trailing `/`).
 */
public final class GeneratedStaticResourceBuildItem extends MultiBuildItem {

    private final String endpoint;

    private final Path file;
    private final byte[] content;

    private GeneratedStaticResourceBuildItem(final String endpoint, final byte[] content, final Path file) {
        requireNonNull(endpoint, "endpoint is required");
        if (!endpoint.startsWith("/")) {
            throw new IllegalArgumentException(
                    "GeneratedStaticResourceBuildItem endpoint must start with '/': %s".formatted(endpoint));
        }
        if (endpoint.endsWith("/")) {
            throw new IllegalArgumentException(
                    "GeneratedStaticResourceBuildItem endpoint must not end with '/': %s".formatted(endpoint));
        }
        this.endpoint = endpoint;
        this.file = file;
        this.content = content;
    }

    /**
     * The resource will be served at {@code '{quarkus.http.root-path}{endpoint}'}
     *
     * @param endpoint the endpoint from the {@code '{quarkus.http.root-path}'} for this generated static resource. It should be
     *        prefixed with {@code '/'}
     * @param content the content of this generated static resource
     */

View on GitHub (pinned to e1c734241f)

Solutions

Prepend '/' to the endpoint before constructing the build item
Normalize the path in a helper that ensures a leading slash
Add a validation guard in the producing build step

Example fix

// before
new GeneratedStaticResourceBuildItem("assets/app.js", content)
// after
new GeneratedStaticResourceBuildItem("/assets/app.js", content)

Defensive patterns

Strategy: validation

Validate before calling

if (endpoint == null || !endpoint.startsWith("/")) {
    throw new IllegalArgumentException("endpoint must start with '/': " + endpoint);
}

Prevention

Always prefix generated endpoints with '/'
Normalize paths in one helper before creating build items
Assert endpoints start with '/' in build-step tests

When it happens

Trigger: A BuildStep creates new GeneratedStaticResourceBuildItem(endpoint, content) or the file-based variant where endpoint is a relative path like "foo/bar.js" or an empty-after-null-check string.

Common situations: Building the path by string concatenation from a config value or artifact id without prepending '/'; stripping the leading slash when normalizing paths; producing a dev-ui or webjar route from a filename.

Related errors

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