add-troubleshooting-and-note

Author: mendonk

docs/docs/Develop/configuration-custom-database.mdx

@@ -42,7 +42,13 @@ Langflow can more efficiently handle multiple users and larger workloads by usin
     LANGFLOW_DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
     ```
 
-    Langflow uses [SQLAlchemy](https://www.sqlalchemy.org/) with the [psycopg](https://www.psycopg.org/) driver to pass SSL parameters directly to the PostgreSQL connection. The following SSL modes are supported:
+    Langflow uses [SQLAlchemy](https://www.sqlalchemy.org/) with the [psycopg](https://www.psycopg.org/) driver to pass SSL parameters directly to the PostgreSQL connection.
+
+    :::note PostgreSQL driver compatibility
+    Langflow requires `psycopg2-binary` or `psycopg[binary]` as the PostgreSQL driver. The `asyncpg` driver is not compatible with Langflow's current database schema due to stricter timezone handling requirements.
+    :::
+
+    The following SSL modes are supported:
 
     - **`sslmode=require`**: Requires SSL connection but doesn't verify server certificate. This option is the least secure, but acceptable for most use cases.
         ```bash

docs/docs/Support/troubleshooting.mdx

@@ -147,6 +147,18 @@ In Langflow OSS, you can follow the error message's instructions to install the
 
 To manage dependencies in Langflow Desktop, see [Install custom dependencies in Langflow Desktop](/install-custom-dependencies#langflow-desktop).
 
+### PostgreSQL asyncpg driver compatibility issue
+
+If you encounter errors when initializing Langflow with a PostgreSQL database, such as:
+
+```text
+sqlalchemy.exc.DBAPIError: (sqlalchemy.dialects.postgresql.asyncpg.Error) <class 'asyncpg.exceptions.DataError'>: invalid input for query argument $7: datetime.datetime(2025, 10, 31, 14, 8, 5... (can't subtract offset-naive and offset-aware datetimes)
+```
+
+This error occurs because `asyncpg` has stricter timezone handling than `psycopg2`, and is not fully compatible with Langflow's current database schema.
+
+To resolve this issue, remove `asyncpg` from your installation and use `psycopg2` instead.
+
 ## Langflow upgrade issues
 
 The following issues can occur when upgrading your Langflow version.