quarkusio/quarkus · error · IllegalArgumentException

Endpoint not found:

Error message

Endpoint not found: 

What it means

findEndpoint resolves an endpoint by its id from the list of deployed WebSocketEndpointBuildItems and throws IllegalArgumentException when no match exists. This surfaces at runtime (e.g. when opening a connection or activating the endpoint context) for an unknown id.

Source

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

    private boolean activateContext(WebSocketsServerBuildConfig.ContextActivation activation, ScopeInfo scope,
            String endpointId, List<WebSocketEndpointBuildItem> endpoints, BeanResolver beanResolver,
            Optional<PermissionsAllowedMetaAnnotationBuildItem> metaPermissionsAllowed,
            boolean securityEnabled, boolean httpUpgradeSecured, SecurityTransformer securityTransformer) {
        return switch (activation) {
            case ALWAYS -> true;
            case AUTO -> needsContext(findEndpoint(endpointId, endpoints).bean, scope, new HashSet<>(), beanResolver,
                    metaPermissionsAllowed, securityEnabled, httpUpgradeSecured, securityTransformer);
            default -> throw new IllegalArgumentException("Unexpected value: " + activation);
        };
    }

    private WebSocketEndpointBuildItem findEndpoint(String endpointId, List<WebSocketEndpointBuildItem> endpoints) {
        for (WebSocketEndpointBuildItem endpoint : endpoints) {
            if (endpoint.id.equals(endpointId)) {
                return endpoint;
            }
        }
        throw new IllegalArgumentException("Endpoint not found: " + endpointId);
    }

    private boolean needsContext(BeanInfo bean, ScopeInfo scope, Set<String> processedBeans, BeanResolver beanResolver,
            Optional<PermissionsAllowedMetaAnnotationBuildItem> metaPermissionsAllowed, boolean securityEnabled,
            boolean httpUpgradeSecured, SecurityTransformer securityTransformer) {
        if (processedBeans.add(bean.getIdentifier())) {

            if (scope.equals(bean.getScope())) {
                // Bean has the given scope
                return true;
            } else if (securityEnabled && BuiltinScope.REQUEST.is(scope)
                    && bean.isClassBean()
                    && bean.hasAroundInvokeInterceptors()
                    && hasSecurityAnnNotOnHttpUpgrade(bean.getTarget().get().asClass(), metaPermissionsAllowed,
                            httpUpgradeSecured, securityTransformer)) {
                // The given scope is RequestScoped, the bean is class-based, has an aroundInvoke interceptor associated and is annotated with a security annotation
                return true;
            }

View on GitHub (pinned to e1c734241f)

Solutions

1. Use the exact id of a deployed endpoint: the fully-qualified class name, or the endpointId/clientId attribute value
2. Check the deployment logs or the endpoint registry for available ids
3. Fix call sites after renaming an endpoint (IDE 'find usages' on the id string)

Example fix

// before
connectionManager.open(WebSocketConnection.ConnectionOpenOptions.builder()
    .endpointId("com.example.OldEndpoint").build());
// after
connectionManager.open(WebSocketConnection.ConnectionOpenOptions.builder()
    .endpointId("com.example.NewEndpoint").build());

// Validate the endpoint id exists before opening a connection
void safeOpen(String endpointId) {
  Set<String> known = Set.of("com.example.ChatSocket", "com.example.EchoSocket"); // or a registry
  if (!known.contains(endpointId))
    throw new IllegalArgumentException("Unknown endpointId: " + endpointId);
}

try {
  connectionManager.open(opts.endpointId(id));
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Endpoint not found")) {
    throw new IllegalStateException("Check endpointId against deployed endpoints", e);
  }
  throw e;
}

When it happens

Trigger: Calling WebSocketConnection.ConnectionOpenOptions with an endpointId that no deployed endpoint declares, or programmatic lookup/activation with a mistyped or renamed id.

Common situations: Renaming an endpoint class or its endpointId and forgetting call sites that reference the old id; typos in the id string; endpoint not deployed due to a build-time exclusion so its id is missing at runtime.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Multiple endpoints [%s, %s] define the same endpoint id: %s
• Multiple client endpoints [%s, %s] define the same endpoint
• Key ${key} not found
• No datasource named '<dataSourceName>' exists
• quarkus.funqy.export does not match a function: ${export}

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