SQLAlchemy OperationalError 🐍 Python

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) connection to server … failed

SQLAlchemy’s DB driver raised an operational error — connection failures, lost connections or locked SQLite databases.

Seen on: Python

Meaning

The text in parentheses is the driver’s own error: connection refused, password authentication failed, server closed the connection, or “database is locked” for SQLite.

Common causes

  • Database unreachable / credentials wrong
  • Connection dropped by the server (idle timeout)
  • SQLite locked by another writer
  • Too many connections

⚡ Quick fix

  1. Read the driver error in parentheses
  2. Use pool_pre_ping=True and pool_recycle to avoid stale connections
  3. Check DATABASE_URL
  4. For SQLite, avoid concurrent writers or use WAL

Detailed fix by platform

Python

  1. engine = create_engine(url, pool_pre_ping=True, pool_recycle=1800)

How to diagnose

  1. Driver error — Text inside the parentheses
  2. Timing — At startup or after idle?

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.