Custom Error Handling in Flask | CodeSignal Learn

Custom Error Handling in Flask | CodeSignal Learn

Custom Error Handling in Flask

In our journey of building and enhancing our Flask application, it's important to handle errors gracefully. This is crucial not only for debugging during development but also for ensuring a smooth user experience when something goes wrong. Just as we discussed middleware that intercepts requests to handle specific tasks, a systematic approach to managing errors involves crafting custom solutions. In this lesson, we will explore how to implement a custom error handler in Flask that manages uncaught exceptions graciously and enhances the user experience with a friendly error page.

Designing a Custom Error Page

Before diving into the logic for error handling, let's design a custom error page that will communicate any issues to users. We'll be creating this file in the app/templates directory. HTML <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Error</title> </head> <body> <!-- Display the error code in a header --> <h1>Error {{code}}</h1> <!-- Display the description of the error --> <p>{{description}}</p> </body> </html> This HTML template provides a simple structure to display error details. The <h1> tag shows the error code, and the <p> tag describes what went wrong.

Flask’s Error Handling Basics

Flask provides a default error page that shows technical details useful for developers, but not for users. To offer a better user experience, we can create custom error pages using the @app.errorhandler decorator, allowing more intuitive error messages. Let's clarify how errors are handled with an example: HTTP Request : A user sends a request to the server. Error? : As the request is processed, Flask checks if an error arises. Complete Request Processing : If there’s no error, the request continues as expected. Activate Error Handler : If an error occurs, the custom error handler is activated. Show Custom Error Page : Finally, the error handler displays a friendly error page to the user.

Implementing the Error Handler Middleware

Sign up

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

To set up middleware that handles exceptions gracefully, we'll be creating a new module in the app/middlewares directory named error_handler.py . from flask import render_template from werkzeug.exceptions import HTTPException def setup_error_handler(app): @app.errorhandler(Exception) def handle_exception(e): # Determine the error code; default to 500 if not an HTTPException code = e.code if isinstance(e, HTTPException) else 500 # Render the custom error page with the error code and description return render_template("error_page.html", code=code, description=str(e)), code The function takes the app instance and decorates it with @app.errorhandler(Exception) to globally handle exceptions through the handle_exception function. Determine Error Code : If the exception is an instance of HTTPException, use e.code as the error code. If it's not an HTTPException, default to a 500 error code, which stands for "Internal Server Error", indicating an unexpected condition that prevented the server from fulfilling the request. Render Custom Error Page : Uses Flask's render_template method to render error_page.html . The rendered page displays the error code and its description. Returns the HTML content along with the status code to ensure that the client is informed of the specific error encountered. This setup allows the application to intercept exceptions and present a user-friendly error page.

Setting Up the Error Handler

Once we have our custom error handler middleware ready, the next step is to integrate it into our Flask application. Here's how we set up the error_handler middleware in our app.py file: from flask import Flask from controllers.todo_controller import todo_controller from middlewares.error_handler import setup_error_handler from models import db from config import Config app = Flask(__name__) app.config.from_object(Config) db.init_app(app) with app.app_context(): db.create_all() # Setup error handler middleware setup_error_handler(app) app.register_blueprint(todo_controller) if __name__ == '__main__': app.run(host='0.0.0.0', port=3000, debug=True) This ensures that errors are efficiently managed and provide the necessary feedback to users through our custom error pages.

Testing the Custom Error Handler

To ensure that our error handler performs as expected, we can introduce a deliberate error in one of our routes inside the controllers/todo_controller.py file. @todo_controller.route('/add', methods=['POST']) def add(): raise Exception("This is a test error") # Raising an intentional exception title = request.form.get('title') description = request.form.get('description') if title and description: todo_service.add(title, description) return redirect(url_for('todo.list_todos')) When a client sends a POST request to the /add endpoint, this deliberate exception is raised, activating the handle_exception middleware function that processes the error and uses the error_page.html template for rendering. The HTML page will display "Error 500" as the title, and the description will read "This is a test error", which matches the string provided in the raised exception.

Python

from flask import render_template
from werkzeug.exceptions import HTTPException

def setup_error_handler(app):
    @app.errorhandler(Exception)
    def handle_exception(e):
        # Determine the error code; default to 500 if not an HTTPException
        code = e.code if isinstance(e, HTTPException) else 500
        # Render the custom error page with the error code and description
        return render_template("error_page.html", code=code, description=str(e)), code

Python

from flask import Flask
from controllers.todo_controller import todo_controller
from middlewares.error_handler import setup_error_handler
from models import db
from config import Config

app = Flask(__name__)

app.config.from_object(Config)

db.init_app(app)

with app.app_context():
    db.create_all()

# Setup error handler middleware
setup_error_handler(app)

app.register_blueprint(todo_controller)

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000, debug=True)

Python

@todo_controller.route('/add', methods=['POST'])
def add():
    raise Exception("This is a test error") # Raising an intentional exception
    title = request.form.get('title')
    description = request.form.get('description')
    if title and description:
        todo_service.add(title, description)
    return redirect(url_for('todo.list_todos'))