Fixing FastAPI Background Task 502 Error on AWS Elastic Beanstalk

Dealing with Background Tasks in FastAPI on Elastic Beanstalk

Deploying a FastAPI application on AWS Elastic Beanstalk can be a smooth experience—until you run into issues like a 502 Bad Gateway error. One common pain point developers face is handling long-running background tasks, which can trigger gateway timeouts. 🚀

Imagine this: You have an API endpoint that generates a PDF file in the background, taking about 30 seconds. Locally, everything works perfectly. But once deployed on Elastic Beanstalk, the API call fails with a frustrating 502 error. You've adjusted the Nginx and Gunicorn timeouts, but the problem persists.

This is a classic scenario where infrastructure settings and background task handling collide. AWS Elastic Beanstalk, by default, might be terminating requests before the background task completes. Understanding why this happens and how to work around it is key to ensuring a smooth deployment.

In this article, we'll explore why FastAPI background tasks cause 502 errors on Elastic Beanstalk, how to configure timeouts properly, and alternative solutions to keep your API running seamlessly. Whether you're dealing with PDF generation, data processing, or any long-running task, these insights will help you tackle the problem efficiently. ⚡

Optimizing FastAPI Background Tasks on AWS Elastic Beanstalk

When running a FastAPI application on AWS Elastic Beanstalk, handling long-running background tasks efficiently is crucial to prevent 502 Bad Gateway errors. The first script we developed uses FastAPI's BackgroundTasks feature to process PDF generation asynchronously. This allows the API to return a response immediately while the task continues running in the background. However, this approach can be problematic on Elastic Beanstalk due to how Gunicorn and Nginx handle request timeouts.

To solve this issue, we introduced a more robust solution using Celery and Redis. In this setup, the FastAPI endpoint sends a task to Celery instead of handling it directly. Celery, running in a separate worker process, picks up the task and executes it asynchronously without blocking the main application. This prevents timeout issues, as the API request completes instantly while Celery handles the processing independently. Imagine an online store generating invoices in bulk—without proper task delegation, the API would struggle under load. 🚀

Another alternative we explored is leveraging AWS SQS (Simple Queue Service). Instead of relying on an internal task queue, this method pushes background jobs to a managed message queue. An external worker service continuously polls SQS for new tasks and processes them asynchronously. This is particularly useful in high-traffic applications, such as a ride-sharing app where each ride generates multiple data processing tasks. By using AWS SQS, we decouple the task execution from the API, improving scalability and reliability.

Finally, on the frontend side, we implemented a polling mechanism to check the task's status. Since the background task takes about 30 seconds, the frontend must periodically query the API to check if the PDF is ready. Instead of overwhelming the server with continuous requests, we implemented an interval-based approach that retries every 5 seconds for a limited number of attempts. This ensures the frontend remains responsive while avoiding unnecessary API load. With this strategy, users requesting document generation, such as tax reports, won’t experience unresponsive UIs while waiting. 📄✅

from fastapi import FastAPI, BackgroundTasks
from celery import Celery
import time
app = FastAPI()
celery = Celery("tasks", broker="redis://localhost:6379/0")
@celery.task
def generate_pdf_task(order_id: str):
    print(f"Generating PDF for order {order_id}")
    time.sleep(30)  # Simulating long processing time
    return f"PDF generated for order {order_id}"
@app.post("/generate-pdf/{order_id}")
async def generate_pdf(order_id: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(generate_pdf_task, order_id)
    return {"message": "PDF generation started"}

import boto3
from fastapi import FastAPI
app = FastAPI()
sqs = boto3.client('sqs', region_name='us-east-1')
queue_url = "https://sqs.us-east-1.amazonaws.com/your-account-id/your-queue-name"
@app.post("/generate-pdf/{order_id}")
async def generate_pdf(order_id: str):
    response = sqs.send_message(
        QueueUrl=queue_url,
        MessageBody=str(order_id)
    )
    return {"message": "PDF generation request sent", "message_id": response['MessageId']}

async function checkPdfStatus(orderId) {
    let attempts = 0;
    const maxAttempts = 5;
    while (attempts < maxAttempts) {
        const response = await fetch(`/get-pdf-url/${orderId}`);
        const data = await response.json();
        if (data.pdf_url) {
            console.log("PDF available at:", data.pdf_url);
            return;
        }
        attempts++;
        await new Promise(resolve => setTimeout(resolve, 5000));
    }
    console.log("PDF generation timed out.");
}

from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_generate_pdf():
    response = client.post("/generate-pdf/test_order")
    assert response.status_code == 200
    assert response.json() == {"message": "PDF generation started"}

Enhancing FastAPI Background Task Handling with WebSockets

One challenge with background tasks in FastAPI is providing real-time updates to users without relying on inefficient polling. A great alternative is using WebSockets, which allow bidirectional communication between the client and the server. Instead of repeatedly querying an endpoint to check the status of a task, the backend can send updates whenever there is progress.

With WebSockets, when a user requests a PDF generation, the server immediately acknowledges the request and starts processing in the background. As the task progresses, WebSocket messages can inform the client about different stages, such as “Processing,” “Uploading,” and “Completed.” This reduces unnecessary API calls and improves user experience, especially in applications like e-commerce invoice generation or report downloads. 🚀

Implementing WebSockets in FastAPI requires using asyncio and the websockets module. A WebSocket connection is established when the frontend listens for updates, and the backend pushes real-time messages. This method is highly efficient compared to traditional polling and is widely used in applications requiring instant updates, such as financial dashboards and collaborative editing tools.