Error Handling

This guide improves error handling for a Flask image upload endpoint. It focuses on robust validation, structured logging, clear HTTP status codes, and graceful failure behavior while preserving the original validation and processing flow (filename/extension/content checks, Pillow verification, and optional quality parameter). Key SEO phrases: Flask image upload, secure file upload, Pillow validation, OpenCV image processing, structured logging, upload endpoint error handling. Below is a consolidated, corrected, and robust implementation of the upload endpoint inside a Flask blueprint. It preserves the validation steps and adds structured logging, appropriate status codes, and a top-level exception handler.

# app/main.py
import logging
from flask import Blueprint, request, jsonify, send_file
import cv2
import numpy as np
import io
import imghdr
from werkzeug.utils import secure_filename
from PIL import Image, UnidentifiedImageError

# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

bp = Blueprint('main', __name__)

@bp.route('/upload', methods=['POST'])
def upload():
    try:
        # Ensure file part exists
        if 'image' not in request.files:
            logger.error('No image part in the request')
            return jsonify({'error': 'No image part in the request'}), 400

        image = request.files['image']

        # Ensure filename is provided
        if image.filename == '':
            logger.error('No image selected for uploading')
            return jsonify({'error': 'No image selected for uploading'}), 400

        # Secure the filename and check extension
        filename = secure_filename(image.filename)
        allowed_extensions = {'png', 'jpg', 'jpeg', 'gif'}
        if not ('.' in filename and filename.rsplit('.', 1)[1].lower() in allowed_extensions):
            logger.error('Invalid file extension: %s', filename)
            return jsonify({'error': 'Invalid file extension'}), 400

        # Read file content and validate binary content
        image_content = image.read()
        image.seek(0)  # Reset the file pointer to the beginning
        content_type = imghdr.what(None, h=image_content)
        if content_type not in allowed_extensions:
            logger.error('Invalid image file content for: %s (detected: %s)', filename, content_type)
            return jsonify({'error': 'Invalid image file'}), 400

        # Validate with Pillow (extra safety)
        try:
            img = Image.open(io.BytesIO(image_content))
            img.verify()  # Raises if image is invalid/corrupt
        except (UnidentifiedImageError, OSError) as e:
            logger.error('Invalid image file (%s): %s', filename, e)
            return jsonify({'error': 'Invalid image file'}), 400

        # Get the quality parameter from the request (default 10)
        quality = request.form.get('quality', 10, type=int)
        if quality is None:
            # If conversion failed, request.form.get may return None
            logger.error('Invalid quality parameter: %s', request.form.get('quality'))
            return jsonify({'error': 'Quality must be an integer between 0 and 100'}), 400
        if quality < 0 or quality > 100:
            logger.error('Invalid quality parameter: %s', quality)
            return jsonify({'error': 'Quality must be between 0 and 100'}), 400

        # Decode image bytes into OpenCV format
        img_array = np.frombuffer(image_content, np.uint8)
        img_cv = cv2.imdecode(img_array, cv2.IMREAD_UNCHANGED)
        if img_cv is None:
            logger.error('Failed to decode image: %s', filename)
            return jsonify({'error': 'Failed to decode image'}), 400

        # Process the image with OpenCV (example: re-encode to JPEG with given quality)
        success, buffer = cv2.imencode('.jpg', img_cv, [int(cv2.IMWRITE_JPEG_QUALITY), quality])
        if not success:
            logger.error('cv2.imencode failed for: %s', filename)
            return jsonify({'error': 'Failed to process image'}), 500

        # Ensure we pass bytes to BytesIO
        img_io = io.BytesIO(buffer.tobytes())

        # Validate the processed image using Pillow
        try:
            processed_img = Image.open(img_io)
            processed_img.verify()
        except (UnidentifiedImageError, OSError) as e:
            logger.error('Failed to process image for %s: %s', filename, e)
            return jsonify({'error': 'Failed to process image'}), 500

        # Reset pointer and return binary response
        img_io.seek(0)
        return send_file(img_io, mimetype='image/jpeg')

    except Exception as e:
        # Catch-all unexpected errors
        logger.exception('An unexpected error occurred while handling /upload: %s', e)
        return jsonify({'error': 'An unexpected error occurred'}), 500

How this implementation improves robustness and observability

Input validation layers:
- Presence of image part in request.files.
- Non-empty filename and secure_filename() usage.
- Extension whitelist check.
- Binary content validation using imghdr.what.
- Final verification with Pillow (Image.verify()).
Parameter validation:
- quality is parsed as an integer with a safe default and bounds check (0–100).
Image processing:
- Decoding via OpenCV (cv2.imdecode) and re-encoding with the requested JPEG quality.
- Re-validation of processed bytes with Pillow before sending.
Error handling and logging:
- Specific client errors return 400 with helpful messages.
- Processing failures return 500 where appropriate.
- logger.exception in the outer except captures stack traces for unexpected errors.

HTTP status mapping and example log messages

Scenario	HTTP status	Example log message
Missing file field	400	`No image part in the request`
Empty filename	400	`No image selected for uploading`
Disallowed extension	400	`Invalid file extension: user.exe`
Binary content mismatch	400	`Invalid image file content for: foo.png (detected: None)`
Pillow verification failed	400	`Invalid image file (foo.jpg): cannot identify image file`
Decoding with OpenCV failed	400	`Failed to decode image: foo.jpg`
cv2.imencode failed	500	`cv2.imencode failed for: foo.jpg`
Processed image invalid	500	`Failed to process image for foo.jpg: cannot identify image file`
Unexpected server error	500	Stack trace captured via `logger.exception`

Always validate both the filename/extension and the file content. File extension checks alone are not sufficient because an attacker can rename arbitrary files.

Global error handlers (optional) For web apps you may prefer HTML pages for 404/500. For REST APIs, JSON responses are usually best. Add these handlers at the application level:

# app/__init__.py or run.py
from flask import Flask, render_template, jsonify

app = Flask(__name__)

@app.errorhandler(404)
def not_found(error):
    # For a web app you might return render_template('404.html'), 404
    return jsonify({'error': 'Not found'}), 404

@app.errorhandler(500)
def internal_error(error):
    # For a web app you might return render_template('500.html'), 500
    return jsonify({'error': 'Internal server error'}), 500

Do not use Flask’s built-in development server for production. Use a production WSGI server (like Gunicorn, uWSGI, or similar) behind a proper reverse proxy.

Testing tips

Use Postman, curl, or similar to POST multipart/form-data with a file field named image.
Include an optional quality form field to control JPEG quality (0–100).
Test both success and failure cases: missing file, invalid extension, corrupted image, invalid quality value.
Inspect server logs (INFO/ERROR) for contextual messages.

Example curl command:

curl -X POST http://localhost:5000/upload \
  -F "image=@/path/to/photo.jpg" \
  -F "quality=75" \
  --output processed.jpg

References and further reading

Flask documentation: https://flask.palletsprojects.com/
Gunicorn: https://gunicorn.org/
uWSGI: https://uwsgi-docs.readthedocs.io/en/latest/
Pillow (PIL): https://python-pillow.org/
OpenCV-Python tutorials: https://docs.opencv.org/
imghdr module: https://docs.python.org/3/library/imghdr.html
Postman Essentials (example testing workflow): https://learn.kodekloud.com/user/courses/postman-essentials

This improved structure provides clearer validation layers, better observability via logging, and more reliable HTTP responses while keeping the original processing flow intact.

Course Introduction

Introduction to AI-Assisted Development

Planning Phase

Development Phase - Backend

Development Phase - Frontend

Project Completion

Watch Video