Fix SQLAlchemy ObjectNotExecutableError: Not an executable object
2026-11-10
sqlalchemy.exc.ObjectNotExecutableError: Not an executable object: 'SELECT id, title FROM documents'
It shows up the moment code written for SQLAlchemy 1.x runs on 2.x and hands a plain Python string to execute(). A typical place is the helper that reads chunks of text for a chatbot out of a database. The statement is right; the type is wrong.
Why it happens
In 2.x Connection.execute() accepts only SQL constructs. The 2.0 migration guide puts it in a code comment: "direct string SQL not supported; use text() or exec_driver_sql() method". Its stated reason is an inconsistency: with a Connection the string went to the driver raw, with a Session it was first converted to text(). The exception class itself is documented as "Raised when an object is passed to .execute() that can't be executed as SQL" in the Core exceptions reference.
Older releases warned first: "Passing a string to Connection.execute() is deprecated and will be removed in version 2.0." If that warning was silenced in your logs, the error looks like it came from nowhere.
The fix
Before:
with engine.connect() as conn:
rows = conn.execute("SELECT id, title FROM documents WHERE source = 'pdf'").all()
After:
from sqlalchemy import text
with engine.connect() as conn:
rows = conn.execute(
text("SELECT id, title FROM documents WHERE source = :source"),
{"source": "pdf"},
).all()
Two details in that change. The value moved out of the SQL into a dictionary, because a text() construct takes named parameters written with a colon, and the migration guide notes that this limits parameters to named rather than positional. And the tutorial warns against building values into the SQL string by formatting. Pass them as bound parameters.
The same error with a Session
Session.execute() takes the same object, so the fix is the same:
from sqlalchemy.orm import Session
with Session(engine) as session:
rows = session.execute(
text("SELECT id, title FROM documents WHERE source = :source"),
{"source": "pdf"},
).all()
A second thing changed at the same time. The tutorial states that the DBAPI connection does not commit automatically, so an INSERT or UPDATE through conn.execute(text(...)) is rolled back when the connection closes unless you call conn.commit(). engine.begin() commits on success instead. If your fix removed the error but new rows still vanish, this is why.
When you need the driver's own syntax
Some code uses positional ? or %s placeholders written for one specific driver. The migration guide names Connection.exec_driver_sql() for that case: it sends the string to the driver untouched, so placeholders follow the driver's rules. It is the narrower tool; text() is the better default, because it does not tie the query to one driver.
Keeping it from coming back
- Search the project for
.execute("and.execute(f"and wrap each hit intext()or rewrite it withselect(). - If a library you call passes strings to
execute()internally, the traceback shows which one. Update that library rather than patching around it. - For queries on mapped tables, prefer
select(); a related SQLAlchemy mistake is covered in the Select attribute error note.