Error Handling in Flask

Analogy categoryAnalogies

Handling Errors Gracefully in Flask

Flask provides several layers for handling errors: HTTP exception classes from Werkzeug (abort(404), abort(403)), the @app.errorhandler decorator for custom error pages, and try/except blocks around view logic for handling application-level exceptions. A well-structured app registers error handlers at the application or blueprint level so that both expected HTTP errors and unexpected exceptions return consistent, informative responses instead of leaking stack traces to users.

🏏

Cricket analogy: When a batter is given out lbw, the umpire has a specific decision-review protocol to follow rather than improvising, just as Flask's abort(404) triggers a specific, standardized error-handling path instead of an ad hoc response.

Custom Error Handlers with @app.errorhandler

The @app.errorhandler decorator binds a function to either an HTTP status code (like 404 or 500) or a specific Python exception class. When Flask cannot match a route or a view calls abort(404), Flask looks for a registered 404 handler and calls it with the exception object, letting you render a custom template or return JSON. For APIs, it's common to catch werkzeug.exceptions.HTTPException broadly and always return JSON with an error code and message rather than rendering HTML.

🏏

Cricket analogy: A team assigns a designated death-overs bowler like Jasprit Bumrah specifically for the last five overs rather than any random bowler, just as @app.errorhandler(404) assigns a specific function specifically to 404 errors.

python

from flask import Flask, jsonify
from werkzeug.exceptions import HTTPException

app = Flask(__name__)

@app.errorhandler(404)
def not_found(e):
    return jsonify(error="not_found", message=str(e)), 404

@app.errorhandler(HTTPException)
def handle_http_exception(e):
    return jsonify(error=e.name, message=e.description), e.code

@app.errorhandler(Exception)
def handle_unexpected_error(e):
    app.logger.exception("Unhandled exception")
    return jsonify(error="internal_error", message="Something went wrong"), 500

Logging and Avoiding Information Leakage

Production error handlers should log the full exception with traceback via app.logger.exception() while returning a sanitized message to the client that never exposes stack traces, file paths, or database details. Flask's debug mode, which shows the interactive Werkzeug debugger with full tracebacks, must be disabled in production (FLASK_DEBUG=0 or debug=False) since it can allow arbitrary code execution if exposed publicly.

🏏

Cricket analogy: A team's internal video analysis of a bowler's weaknesses stays confidential within the dressing room while only the match result is shared publicly, just as full tracebacks stay in server logs while users see a sanitized error message.

Use app.logger.exception() inside a broad Exception handler to capture the full stack trace in your logs, while the JSON or HTML response sent to the client stays generic — this separation keeps debugging information available to developers without leaking it to end users.

Never deploy with debug=True or FLASK_DEBUG=1 in production. The Werkzeug interactive debugger exposes a Python console directly in the browser on unhandled exceptions, which is a remote code execution vulnerability if the app is publicly reachable.

Flask separates error handling into HTTP-level (abort/errorhandler on status codes) and exception-level (Python exception classes) handling.
@app.errorhandler binds a function to a status code or exception class, letting you return custom HTML or JSON responses.
APIs typically catch werkzeug.exceptions.HTTPException broadly to guarantee consistent JSON error responses across all HTTP errors.
A catch-all errorhandler(Exception) prevents unhandled exceptions from leaking raw tracebacks to users.
app.logger.exception() should log full tracebacks server-side while responses to clients stay sanitized.
Debug mode must never be enabled in production due to the Werkzeug debugger's remote code execution risk.
Error handlers can be registered at the blueprint level for module-specific error behavior.