Skip to main content

FastAPI application crashing on Linux — recovery guide

TL;DR

How to diagnose and recover a FastAPI application that crashes repeatedly on Linux.

Key facts

Topic
Production error triage
Stack
FastAPI / Uvicorn / Linux

TL;DR

A FastAPI application crashing on Linux typically exits with a non-zero code, leaving Uvicorn's systemd service in failed state. Users see connection refused or 502 errors until the process is manually restarted or systemd's auto-restart kicks in.

Common causes

  • An unhandled exception in a startup lifespan handler or @app.on_event("startup") callback
  • Missing Python dependencies after deployment (incomplete virtual environment)
  • Port already in use — another process grabbed the port
  • Environment variables missing or incorrectly set
  • Out-of-memory kill by the Linux OOM killer

Diagnosis workflow

Check systemd status and logs:

systemctl status fastapi-app
journalctl -u fastapi-app --since "30 minutes ago" --no-pager

Check for OOM kills:

dmesg | grep -i "oom\|killed process"

Verify the port is available:

ss -tlnp | grep :8000

Systemd service configuration

A robust systemd unit file for FastAPI:

[Unit]
Description=FastAPI Application
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/myapp
ExecStart=/var/www/myapp/venv/bin/uvicorn main:app \
    --host 0.0.0.0 --port 8000 --workers 4
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1
EnvironmentFile=/var/www/myapp/.env

[Install]
WantedBy=multi-user.target

The Restart=always and RestartSec=5 settings ensure systemd restarts the process after a crash with a 5-second delay.

Quick recovery

sudo systemctl restart fastapi-app
sudo systemctl status fastapi-app
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health

Prevention

  • Add health check endpoints and test them in your CI pipeline
  • Pin all dependencies in requirements.txt with exact versions
  • Run python -c "from main import app" as a deploy smoke test before restarting
  • Set OOMScoreAdjust=-500 in systemd to reduce OOM kill probability for your application process

Where Reflex helps

Reflex monitors your systemd service state and Uvicorn process health. When it detects a crash, Reflex can restart the service, verify the health endpoint responds, and alert your team with a timeline that includes the crash reason from journal logs. See How it works.