quarkusio/quarkus · error · IllegalArgumentException

Name cannot start with '/':${name}

Error message

Name cannot start with '/':${name}

What it means

GeneratedClassBuildItem represents a class generated at build time. Names must be resource-relative (e.g. "com/acme/Foo.class") because the item is later stored in the application's generated classes output; a leading '/' would produce a wrong path. The constructor rejects any name starting with '/' with IllegalArgumentException.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/builditem/GeneratedClassBuildItem.java:34

 * These generated classes are typically added to the application's class path or packaged into the final artifact.
 */
public final class GeneratedClassBuildItem extends MultiBuildItem {

    final boolean applicationClass;
    final String name;
    String binaryName;
    String internalName;
    String packageName;
    final byte[] classData;
    final String source;

    public GeneratedClassBuildItem(boolean applicationClass, String name, byte[] classData) {
        this(applicationClass, name, classData, null);
    }

    public GeneratedClassBuildItem(boolean applicationClass, String name, byte[] classData, String source) {
        if (name.startsWith("/")) {
            throw new IllegalArgumentException("Name cannot start with '/':" + name);
        }
        this.applicationClass = applicationClass;
        this.name = name;
        this.classData = classData;
        this.source = source;
    }

    public boolean isApplicationClass() {
        return applicationClass;
    }

    /**
     * {@return the <em>binary name</em> of the class, which is delimited by <code>.</code> characters}
     */
    public String binaryName() {
        String binaryName = this.binaryName;
        if (binaryName == null) {
            binaryName = this.binaryName = name.replace('/', '.');

View on GitHub (pinned to e1c734241f)

Solutions

1. Strip the leading '/' before constructing the item: name.startsWith("/") ? name.substring(1) : name.
2. Build the name from the class binary name, e.g. className.replace('.', '/') + ".class", which never yields a leading slash.
3. If you control a shared helper that emits resource names, normalize it there so all callers benefit.

Example fix

// before
String name = "/" + className.replace('.', '/') + ".class";
outputProducer.produce(new GeneratedClassBuildItem(true, name, bytes));
// after
String name = className.replace('.', '/') + ".class";
outputProducer.produce(new GeneratedClassBuildItem(true, name, bytes));

String toGeneratedClassName(String className) {
    String name = className.replace('.', '/') + ".class";
    if (name.startsWith("/")) throw new IllegalArgumentException(name);
    return name;
}

boolean isValidGeneratedClassName(String name) {
    return name != null && !name.isEmpty() && !name.startsWith("/") && name.endsWith(".class");
}

try {
    produce(new GeneratedClassBuildItem(true, name, classData));
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Name cannot start with '/'")) {
        produce(new GeneratedClassBuildItem(true, name.substring(1), classData));
        return;
    }
    throw e;
}

When it happens

Trigger: Constructing new GeneratedClassBuildItem(applicationClass, "/com/acme/Foo.class", classData) in a build step — i.e. passing a name that begins with a forward slash.

Common situations: Extension authors who previously produced byte-code via a resource-style API (where '/path' is conventional) and reused that path string; string concatenation of '/' + name from class-name-to-path conversion code.

Related errors

• messageStarts cannot be empty
• 'target' can only be a class, a field or a method: <target>
• Unsupported object of type ${object.getClass()}. Supported t
• Type {type} should be handled by the switch
• Unsupported naming strategy:

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