apache/shenyu · error · NoFallbackAvailableException

No fallback available.

Error message

No fallback available.

What it means

When the underlying remote call through ShenyuClientMethodHandler throws, invoke() checks for a configured fallbackFactory. If none is set it wraps the original cause in NoFallbackAvailableException("No fallback available."). The real failure reason is always the cause of this exception.

Solutions

1. Inspect the cause of NoFallbackAvailableException (getCause()) to fix the root failure — connection, timeout, or serialization.
2. Provide a fallbackFactory when creating the client so failures degrade gracefully instead of propagating.
3. Fix connectivity to the gateway (host/port, firewall, gateway process running).
4. Add timeouts/retries appropriate to the operation so transient errors are absorbed.

Example fix

// before
ShenyuClientFactoryBean factoryBean = new ShenyuClientFactoryBean(OrderApi.class, url);
// after
factoryBean.setFallbackFactory(new OrderApiFallbackFactory()); // returns defaults on failure

try {
    return orderApi.getById(id);
} catch (NoFallbackAvailableException e) {
    log.warn("shenyu call failed", e.getCause());
    return OrderDTO.empty(); // local default
}

When it happens

Trigger: Any remote-call failure (connection refused, timeout, non-2xx from the gateway, JSON decode error) on a @ShenyuClient proxy that was created without a fallbackFactory.

Common situations: Gateway down or port wrong; network partition or timeout under load; response body not deserializable; developer never wired a fallback because the client was assumed reliable.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• HTTP status error from backend response (dynamic status…

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/cee6203442217c2d. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-sdk/shenyu-sdk-spring/src/main/java/org/apache/shenyu/sdk/spring/proxy/ShenyuClientInvocationHandler.java:89

        fallbackFactory = getFallbackFactory(shenyuClientFactoryBean.getFallback(),
                shenyuClientFactoryBean.getFallbackFactory());
        buildMethodHandlerMap(apiClass, shenyuClient);
    }

    @Override
    public Object invoke(final Object proxy, final Method method, final Object[] args) throws Throwable {

        ShenyuClientMethodHandler handler = methodHandlerMap.get(method);
        if (ObjectUtils.isEmpty(handler)) {
            throw new ShenyuException(String.format("the method cannot be called, please check the annotation and configuration, method %s", method.getName()));
        }
        Object result;
        try {
            result = handler.invoke(args);
        } catch (Throwable throwable) {
            LOG.error("ShenYu Client invoke error  ", throwable);
            if (Objects.isNull(fallbackFactory)) {
                throw new NoFallbackAvailableException("No fallback available.", throwable);
            }
            Object fallback = fallbackFactory.create(throwable);
            result = method.invoke(fallback, args);
        }
        return result;
    }

    private void buildMethodHandlerMap(final Class<?> apiClass, final ShenyuClient shenyuClient) {
        // parseAndValidate RequestTemplate
        final List<RequestTemplate> requestTemplates = contract.parseAndValidateRequestTemplate(apiClass, shenyuClientFactoryBean);

        final ShenyuSdkClient shenyuSdkClient = applicationContext.getBean(ShenyuSdkClient.class);
        final Map<String, AnnotatedParameterProcessor> annotatedParameterProcessorMap = applicationContext.getBeansOfType(AnnotatedParameterProcessor.class);
        Collection<AnnotatedParameterProcessor> annotatedParameterProcessors = annotatedParameterProcessorMap.values();
        annotatedParameterProcessors = annotatedParameterProcessors.stream().sorted(Comparator.comparing(AnnotatedParameterProcessor::order)).collect(Collectors.toList());
        Map<Class<? extends Annotation>, AnnotatedParameterProcessor> annotatedArgumentProcessors = toAnnotatedArgumentProcessorMap(annotatedParameterProcessors);
        for (RequestTemplate requestTemplate : requestTemplates) {
            requestTemplate.setUrl(shenyuClientFactoryBean.getUrl());

View on GitHub (pinned to 567142e072)