Opened 5 years ago

Last modified 5 years ago

#30858 closed Cleanup/optimization

Ambiguous phrasing in the Error Reporting documentation — at Initial Version

Reported by: ForgottenLords Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords: Error Reporting, Documentation
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

In the Error Reporting documentation, the following phrasing is used (Emphasis Mine):

When DEBUG is False, Django will email the users listed in the ADMINS setting whenever your code raises an unhandled exception and results in an internal server error (HTTP status code 500)

Myself and several others in my development team read this as:
Whenever your code raises an unhandled exception resulting in an internal server error

when in actuality it should read more like the following to better reflect the correct behavior of Django:
Whenever your code raises an unhandled exception, or your view returns a response with a status code 500

The nuance is perhaps small, but we had been operating under the assumption that views returning a response with status_code=500 would be 'silent' and not generate emails as they are internal server errors, but have already been correctly and safely handled by our code but we still want to send the client a 500 to inform them that the response could not be completed as expected. We assumed based on that line that emails would ONLY be sent as a result of unhandled exceptions.

It may be worth expanding on the error handling to allow users to return 'safe' 500 responses that will not be logged, and in fact Django does check for the _has_been_logged property already before logging the response, which we can set in our code already so perhaps just exposing that to the documentation in a little note would be useful to people who want to send 500 responses without sending emails might be sufficient.

Change History (0)

Note: See TracTickets for help on using tickets.
Back to Top