{"record":{"id":"a31c5662fd51bdb8","repo":"tursodatabase/turso","slug":"a-sqliteconnection-wrapping-a-tursoconnection-must","errorCode":null,"errorMessage":"A SqliteConnection wrapping a TursoConnection must remain a direct remote or embedded replica connection.","messagePattern":"A SqliteConnection wrapping a TursoConnection must remain a direct remote or embedded replica connection\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"bindings/dotnet/src/Turso.Data.Sqlite/SqliteConnection.cs","lineNumber":74,"sourceCode":"        _managedConnection = connection;\n        _ownsManagedConnection = ownsConnection;\n        _wrapsManagedConnection = true;\n        _readOnly = options.Mode == SqliteOpenMode.ReadOnly;\n    }\n\n    [AllowNull]\n    public override string ConnectionString\n    {\n        get => _connectionOptions.ConnectionString;\n        set\n        {\n            if (State == ConnectionState.Open)\n                throw new InvalidOperationException(Properties.Resources.ConnectionStringRequiresClosedConnection);\n\n            var options = new SqliteConnectionStringBuilder(value);\n            if (_wrapsManagedConnection && options.IsLocal)\n            {\n                throw new InvalidOperationException(\n                    \"A SqliteConnection wrapping a TursoConnection must remain a direct remote or embedded replica connection.\");\n            }\n\n            ConfigureManagedConnection(options);\n            _connectionOptions = options;\n            _defaultTimeout = null;\n        }\n    }\n\n    public override string Database => _managedConnection?.Database ?? \"main\";\n\n    public override string DataSource => _managedConnection?.DataSource ?? _dataSource ?? _connectionOptions.DataSource;\n\n    public int DefaultTimeout\n    {\n        get => _defaultTimeout ?? _connectionOptions.DefaultTimeout;\n        set\n        {","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/tursodatabase/turso/blob/6c7252267988c76e632af00a671e4b9788dfae13/bindings/dotnet/src/Turso.Data.Sqlite/SqliteConnection.cs#L56-L92","documentation":"This InvalidOperationException is thrown by the SqliteConnection.ConnectionString setter when a connection that already wraps a TursoConnection is assigned a local connection string. The wrapper must stay on the managed direct-remote/embedded-replica backend for its lifetime.","triggerScenarios":"Setting conn.ConnectionString = \"Data Source=local.db\" (or any IsLocal string) on a SqliteConnection constructed around a TursoConnection, whether the connection is open or closed (the open-state guard fires first if open).","commonSituations":"Code that reuses one SqliteConnection object and swaps connection strings between local and remote targets; config-driven connection strings pointing to a local file for a wrapper meant to be remote.","solutions":["Assign only direct remote or embedded replica connection strings to a wrapping SqliteConnection","Create a new, separate SqliteConnection(connectionString) for local usage instead of mutating the wrapper","Track the _wrapsManagedConnection flag in your own code and branch before reassigning the connection string"],"exampleFix":"// before\nmanagedWrapper.ConnectionString = \"Data Source=local.db\"; // throws\n\n// after\nvar localConn = new SqliteConnection(\"Data Source=local.db\");","handlingStrategy":"validation","validationCode":"if (new SqliteConnectionStringBuilder(cs).IsLocal && wrapsManaged)\n    throw new InvalidOperationException(\"Use a fresh connection for local targets.\");","typeGuard":null,"tryCatchPattern":"try { conn.ConnectionString = cs; }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"must remain\"))\n{\n    conn = new SqliteConnection(cs);\n}","preventionTips":["Never mutate ConnectionString on wrapped connections","Branch local/remote at connection creation time"],"tags":["dotnet","connection-string","invalid-state-transition"],"backgroundTag":"invalid-state-transition","analyzedSha":"6c7252267988c76e632af00a671e4b9788dfae13","analyzedAt":"2026-09-06T07:15:26.990Z","contentChangedAt":"2026-09-06T07:15:26.990Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}