tursodatabase/turso · critical · Misuse

sync connect did not return a connection

Error message

sync connect did not return a connection

What it means

A defensive invariant at the end of turso.sync.connect: after sync_db.create() succeeds, sync_db.connect() must return a native PyTursoConnection; any other type raises Misuse("sync connect did not return a connection"). It is not reachable through correct usage — it indicates the Python layer and the native turso extension it loaded do not agree (version skew or a corrupted install), i.e. a binding-level bug rather than a user error.

Source

Thrown at bindings/python/turso/lib_sync.py:519

        if partial_sync_experimental is not None
        else None,
        remote_encryption_key=remote_encryption_key,
        remote_encryption_cipher=remote_encryption_cipher,
        push_operations_threshold=push_operations_threshold,
        pull_bytes_threshold=pull_bytes_threshold,
        logical_mvcc_pull=logical_mvcc_pull,
    )

    # Create sync database holder
    sync_db: PyTursoSyncDatabase = py_turso_sync_new(db_cfg, sync_cfg)

    # Prepare + open the database with create()
    _run_op(sync_db, sync_db.create(), http_ctx)

    # Connect to obtain PyTursoConnection
    conn_obj = _run_op(sync_db, sync_db.connect(), http_ctx)
    if not isinstance(conn_obj, PyTursoConnection):
        raise Misuse("sync connect did not return a connection")

    # Wrap into ConnectionSync that integrates sync IO into DB operations
    return ConnectionSync(conn_obj, sync=sync_db, http_ctx=http_ctx, isolation_level=isolation_level)

View on GitHub (pinned to bad083fafb)

Solutions

1. Reinstall cleanly: `pip install --force-reinstall --no-cache-dir pyturso` so Python and native layers come from one build
2. Ensure a single environment is active (no stale .so from another venv or editable install shadowing the package)
3. If it persists on a clean install of the latest release, report it upstream with the exact pyturso and turso package versions — it is an internal contract violation

Example fix

# before: partial upgrade leaves mismatched layers
pip install pyturso  # reuses cached/stale native extension

# after
pip install --force-reinstall --no-cache-dir pyturso
python -c "import turso; print(turso.__version__)"

import turso

# Pin Python and native layers to one coherent install at startup
def assert_turso_install_healthy() -> None:
    from turso.lib import connect
    conn = connect(":memory:")
    conn.close()  # smoke test that the native extension matches the Python layer

try:
    conn = turso.sync.connect(path, remote_url=remote_url)
except Exception as e:
    if "sync connect did not return a connection" in str(e):
        raise RuntimeError(
            "pyturso native/Python layer mismatch — run: "
            "pip install --force-reinstall --no-cache-dir pyturso"
        ) from e
    raise

When it happens

Trigger: Mismatched versions between the pyturso Python package and the native turso extension module it imports (e.g. after a partial upgrade, mixing a stale installed extension with a newer wheel, or an editable checkout shadowing a released package); monkeypatched/stale .so or .pyd loaded from an old environment.

Common situations: Upgrading pyturso in-place with cached wheels; virtualenvs reusing a system-wide native extension; Docker layers with partially copied site-packages; CI caches holding an old native artifact.

Related errors

• remote_url is not available
• pyturso's SQLAlchemy dialects require SQLAlchemy >= 2.0.45 (
• TursoSyncDialect does not support host/port in URL. The loca
• Expected turso.sync.ConnectionSync, got {type(dbapi_conn).__
• unknown error type ${name} from Turso

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/21e5cf9b312d17bc. Report an issue: GitHub.