{"record":{"id":"21e5cf9b312d17bc","repo":"tursodatabase/turso","slug":"sync-connect-did-not-return-a-connection","errorCode":null,"errorMessage":"sync connect did not return a connection","messagePattern":"sync connect did not return a connection","errorType":"exception","errorClass":"Misuse","httpStatus":null,"severity":"critical","filePath":"bindings/python/turso/lib_sync.py","lineNumber":519,"sourceCode":"        if partial_sync_experimental is not None\n        else None,\n        remote_encryption_key=remote_encryption_key,\n        remote_encryption_cipher=remote_encryption_cipher,\n        push_operations_threshold=push_operations_threshold,\n        pull_bytes_threshold=pull_bytes_threshold,\n        logical_mvcc_pull=logical_mvcc_pull,\n    )\n\n    # Create sync database holder\n    sync_db: PyTursoSyncDatabase = py_turso_sync_new(db_cfg, sync_cfg)\n\n    # Prepare + open the database with create()\n    _run_op(sync_db, sync_db.create(), http_ctx)\n\n    # Connect to obtain PyTursoConnection\n    conn_obj = _run_op(sync_db, sync_db.connect(), http_ctx)\n    if not isinstance(conn_obj, PyTursoConnection):\n        raise Misuse(\"sync connect did not return a connection\")\n\n    # Wrap into ConnectionSync that integrates sync IO into DB operations\n    return ConnectionSync(conn_obj, sync=sync_db, http_ctx=http_ctx, isolation_level=isolation_level)\n","sourceCodeStart":501,"sourceCodeEnd":523,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/python/turso/lib_sync.py#L501-L523","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reinstall cleanly: `pip install --force-reinstall --no-cache-dir pyturso` so Python and native layers come from one build","Ensure a single environment is active (no stale .so from another venv or editable install shadowing the package)","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"],"exampleFix":"# before: partial upgrade leaves mismatched layers\npip install pyturso  # reuses cached/stale native extension\n\n# after\npip install --force-reinstall --no-cache-dir pyturso\npython -c \"import turso; print(turso.__version__)\"","handlingStrategy":"validation","validationCode":"import turso\n\n# Pin Python and native layers to one coherent install at startup\ndef assert_turso_install_healthy() -> None:\n    from turso.lib import connect\n    conn = connect(\":memory:\")\n    conn.close()  # smoke test that the native extension matches the Python layer","typeGuard":null,"tryCatchPattern":"try:\n    conn = turso.sync.connect(path, remote_url=remote_url)\nexcept Exception as e:\n    if \"sync connect did not return a connection\" in str(e):\n        raise RuntimeError(\n            \"pyturso native/Python layer mismatch — run: \"\n            \"pip install --force-reinstall --no-cache-dir pyturso\"\n        ) from e\n    raise","preventionTips":["Install with --no-cache-dir when upgrading pyturso to avoid stale native artifacts","Avoid mixing an editable checkout with a released install of the same package","Run a tiny connect(':memory:') smoke test at application startup to catch binding skew early","Report persistent occurrences upstream with exact package versions — it is an internal invariant"],"tags":["python","sync","native-binding","version-mismatch","installation"],"backgroundTag":"native-binding-incompatibility","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}