quarkusio/quarkus · error · WebSocketException

Unable to create endpoint instance:

Error message

Unable to create endpoint instance: 

What it means

When a client connects to a server endpoint, WebSockets Next must instantiate the endpoint bean class reflectively (via the container). Endpoints.createEndpoint catches any Exception during instantiation/wiring and rethrows it as WebSocketException 'Unable to create endpoint instance: <className>', preserving the cause.

Source

Thrown at extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/Endpoints.java:453

            if (cl == null) {
                cl = WebSocketServerRecorder.class.getClassLoader();
            }
            @SuppressWarnings("unchecked")
            Class<? extends WebSocketEndpoint> endpointClazz = (Class<? extends WebSocketEndpoint>) cl
                    .loadClass(endpointClassName);

            ErrorInterceptor errorInterceptor = telemetrySupport == null ? null : telemetrySupport.getErrorInterceptor();
            WebSocketEndpoint endpoint = (WebSocketEndpoint) endpointClazz
                    .getDeclaredConstructor(WebSocketConnectionBase.class, Codecs.class, ContextSupport.class,
                            SecuritySupport.class, ErrorInterceptor.class)
                    .newInstance(connection, codecs, contextSupport, securitySupport, errorInterceptor);
            if (telemetrySupport != null) {
                return telemetrySupport.decorate(endpoint, connection);
            }

            return endpoint;
        } catch (Exception e) {
            throw new WebSocketException("Unable to create endpoint instance: " + endpointClassName, e);
        }
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Inspect the wrapped cause 'Caused by' to find the root failure and fix it
2. Verify all beans injected into the endpoint are available and their scopes permit creation
3. Ensure @PostConstruct logic cannot throw in the target environment (e.g. missing config properties)
4. For native builds, confirm the endpoint is discovered via annotation rather than manual reflection registration

Example fix

// before
class Sock {
    @Inject MissingBean bean; // unsatisfied -> instantiation fails
}
// after
@ApplicationScoped
class MissingBean { }
class Sock {
    @Inject MissingBean bean; // now resolvable
}

// verify endpoint dependencies are satisfied before accepting connections
void checkEndpoint(Class<?> endpoint) {
    Instance<?> inst = Arc.container().select(endpoint);
    if (!inst.isResolvable())
        throw new IllegalStateException("Endpoint bean not resolvable: " + endpoint);
}

try {
    connection = client.connect().await().indefinitely();
} catch (WebSocketException e) {
    if (e.getMessage().startsWith("Unable to create endpoint instance")) {
        log.error("Endpoint wiring failed", e.getCause()); // inspect cause
    }
}

When it happens

Trigger: The endpoint bean cannot be created at connection time — CDI bean lookup/instantiation fails, a constructor throws, a dependent bean dependency is unsatisfied, the class failed to initialize, or the bean scope prohibits creation in the current context.

Common situations: Endpoint class depends on a bean not available at connection time; an @PostConstruct throws; wrong bean scope (e.g. @Singleton with unsatisfied dependency); native-image missing reflection config for a manually registered class.

Related errors

• The '%s' CDI bean injection point was detected, but there is
• The @Blocking, @NonBlocking and @RunOnVirtualThread annotati
• Multiple @Inject constructors on ${theClass}
• Unable to find handler class with name <handler> make sure t
• Multiple handler classes, either specify the quarkus.lambda.

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