quarkusio/quarkus · error · WebSocketServerException

Enclosing class not found in index:

Error message

Enclosing class not found in index: 

What it means

For nested endpoint classes the processor computes the full path prefix by resolving enclosing classes in the Jandex index. If an enclosing class cannot be found in the index, the build fails. Note the message prints the null variable, so the class name is effectively missing from the output — the actual name is the enclosingClassName passed to getPathPrefix.

Source

Thrown at extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/WebSocketProcessor.java:1065

        return path.startsWith("/") ? sb.toString() : "/" + sb.toString();
    }

    public static String getOriginalPath(String path) {
        StringBuilder sb = new StringBuilder();
        Matcher m = TRANSLATED_PATH_PARAM_PATTERN.matcher(path);
        while (m.find()) {
            // Replace :foo with {foo}
            String match = m.group();
            m.appendReplacement(sb, "{" + match.subSequence(1, match.length()) + "}");
        }
        m.appendTail(sb);
        return sb.toString();
    }

    static String getPathPrefix(IndexView index, DotName enclosingClassName) {
        ClassInfo enclosingClass = index.getClassByName(enclosingClassName);
        if (enclosingClass == null) {
            throw new WebSocketServerException("Enclosing class not found in index: " + enclosingClass);
        }
        AnnotationInstance webSocketAnnotation = enclosingClass.annotation(WebSocketDotNames.WEB_SOCKET);
        if (webSocketAnnotation != null) {
            String path = getPath(webSocketAnnotation.value("path").asString());
            if (enclosingClass.nestingType() == NestingType.INNER) {
                return mergePath(getPathPrefix(index, enclosingClass.enclosingClass()), path);
            } else {
                return path.endsWith("/") ? path.substring(path.length() - 1) : path;
            }
        }
        return "";
    }

    private void validateOnPingMessage(Callback callback) {
        if (KotlinUtils.isKotlinMethod(callback.method)) {
            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())
                    && !callback.isKotlinSuspendFunctionReturningUnit()) {
                throw new WebSocketServerException(

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the enclosing class is a normal, indexed application class (avoid placing endpoints inside generated/proxied/excluded classes).
2. Prefer top-level endpoint classes to avoid the enclosing-class resolution path entirely.
3. If nesting is required, keep the whole nesting chain in src/main/java of the indexed module.
4. Inspect the build index: confirm the enclosing class name appears in the application's Jandex index before filing a bug.

Example fix

// before (enclosing class may be unindexed/generated)
public class GeneratedHolder { @WebSocket(path = "/ws") public class Nested { } }

// after
@WebSocket(path = "/ws")
public class MyEndpoint { }

// Prefer top-level endpoint classes; if nested, verify the enclosing class is a plain indexed class
static void checkEnclosing(Class<?> endpoint) {
    Class<?> outer = endpoint.getEnclosingClass();
    if (outer != null && (outer.isSynthetic() || outer.getName().contains("$")))
        throw new IllegalStateException("Enclosing class " + outer + " may not be in the Jandex index; use a top-level endpoint");
}

When it happens

Trigger: A @WebSocket endpoint declared as a nested/inner class whose enclosing class is not part of the build-time index (not indexed, excluded from indexing, or synthesized), while the processor walks enclosingClass() chains.

Common situations: Nested endpoint classes inside classes that are themselves excluded from the index; build setups removing classes from Jandex indexing; proxies or generated enclosing classes; exotic packaging where the enclosing class lives outside the indexed artifacts.

Related errors

• The class ${clazzName} not found in the index
• Invalid type:
• Injected class not found in index:
• The original implementation class of a gRPC service not foun
• Couldn't find id field of ${classInfo}

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