Error handling from filter modules

Steven Hartland steven.hartland at
Fri Oct 16 17:15:30 UTC 2015

On 16/10/2015 13:20, Maxim Dounin wrote:
> Hello!
> On Fri, Oct 16, 2015 at 02:36:13AM +0100, Steven Hartland wrote:
>> I'm making changes to a filter module and when it detected an error it
>> returned NGX_ERROR however the response generated to the client isn't
>> the expected 500 internal server error I would have expected given said
>> return.
>> So the question is do filters have to manually call
>> ngx_http_finalize_request(r, NGX_HTTP_INTERNAL_SERVER_ERROR); or is it
>> expected that the upper layers should actually do the right thing and
>> ensure the client doesn't get a bad response generated from the current
>> state of r with no indication an error occurred?
> In filters, it's already to late to return anything in case of
> errors.  In body filters, it's way too late - the response was
> already partially sent.  And in header filters there is a chance that
> other filters allocated something response-specific, and an
> attempt to return a different response will break things.  So,
> when you return NGX_ERROR from a filter, the connection is just
> closed.
There are a few core filters which seem to contradict this;

range does:
return ngx_http_range_not_satisfiable(r, ctx);

while image does:
return ngx_http_filter_finalize_request(r,

The range filter is the one I was looking at, picking back up the work 
you gave feedback on a while back with regards allow partial content 
responses to be used to satisfy range requests.

During testing for failures I triggered the NGX_ERROR case here:

When I triggered this case client recieved an broken 200 response, where 
as if I did finalise the request I could deliver a 500 response, so was 
wondering if this would be correct in this situation?
> If you absolutely must return an error from a filter - like, e.g.,
> not modified filter do for 416 responses - there is a special
> function to do this, ngx_http_filter_finalize_request().  It's
> very fragile though, and I wouldn't recommend using it unless you
> are sure you must do it.
Yer I found that later but seems my mail's been playing up today, so 
sorry for the crossed replies.

Thanks for the feedback :)


More information about the nginx-devel mailing list