Mastering Zuul Exception Handling: From Try‑Catch to Custom Error Filters

Shortcomings of Existing Approaches

Earlier we described two ways to handle exceptions thrown inside Zuul filters: adding try-catch blocks in each filter or leveraging the lifecycle of error filters to process exceptions from pre, route, and post stages. While both can be combined, they still leave gaps that become evident after deeper source‑code analysis.

Understanding Zuul's Filter Dispatch

When an external request reaches the API‑gateway service, Zuul schedules filters in three phases. The core implementation resides in com.netflix.zuul.http.ZuulServlet.service and looks like this:

try { preRoute(); } catch (ZuulException e) { error(e); postRoute(); return; }
try { route(); } catch (ZuulException e) { error(e); postRoute(); return; }
try { postRoute(); } catch (ZuulException e) { error(e); return; }

The three try-catch blocks correspond to pre, route, and post filters. All caught exceptions are delegated to an error filter. After the error filter finishes, only exceptions from the post phase are processed further; exceptions from pre or route are effectively lost, which explains the earlier deficiency.

Analysis and Optimization

Both previous solutions rely on adding error.* attributes to the request context, which the SendErrorFilter later consumes. However, when an exception originates from a post filter, the error filter handles it but no subsequent post filter runs, so those attributes are never read, resulting in empty responses.

To address this, we modify the custom ThrowExceptionFilter to be of type post and remove its internal try-catch, allowing the exception to propagate.

One straightforward fix is to let the error filter directly construct the response, but that duplicates error‑handling code. Instead, we keep the existing SendErrorFilter as the single point of response generation and ensure that exceptions from post filters are routed to it.

Extending the Filter Processor

We create a subclass of SendErrorFilter named ErrorExtFilter that overrides filterType(), filterOrder(), and shouldFilter(). The shouldFilter() method must determine whether the caught exception originated from a post filter.

public class ErrorExtFilter extends SendErrorFilter {
    @Override
    public String filterType() { return "error"; }
    @Override
    public int filterOrder() { return 30; }
    @Override
    public boolean shouldFilter() {
        // TODO: return true only for exceptions from POST filters
        return false;
    }
}

Because the request context does not store the source filter, we extend the core FilterProcessor to capture the failing filter and store it in the context.

public class DidiFilterProcessor extends FilterProcessor {
    @Override
    public Object processZuulFilter(ZuulFilter filter) throws ZuulException {
        try {
            return super.processZuulFilter(filter);
        } catch (ZuulException e) {
            RequestContext ctx = RequestContext.getCurrentContext();
            ctx.set("failed.exception", e);
            ctx.set("failed.filter", filter);
            throw e;
        }
    }
}

With this processor in place, ErrorExtFilter.shouldFilter() can retrieve the stored filter and decide:

public class ErrorExtFilter extends SendErrorFilter {
    @Override
    public String filterType() { return "error"; }
    @Override
    public int filterOrder() { return 30; }
    @Override
    public boolean shouldFilter() {
        RequestContext ctx = RequestContext.getCurrentContext();
        ZuulFilter failedFilter = (ZuulFilter) ctx.get("failed.filter");
        if (failedFilter != null && failedFilter.filterType().equals("post")) {
            return true;
        }
        return false;
    }
}

Finally, we activate the custom processor in the application’s main class:

FilterProcessor.setProcessor(new DidiFilterProcessor());

Key Takeaways

Standard error filters only handle exceptions from pre and route phases; post‑phase exceptions require additional routing.

Extending FilterProcessor allows us to record the failing filter and its exception.

A custom error filter with a precise shouldFilter() implementation ensures that only post‑filter exceptions trigger the unified error response.