tursodatabase/turso · error · ArgumentException

Only direct remote and embedded replica Turso connections ca

Error message

Only direct remote and embedded replica Turso connections can be wrapped.

What it means

This ArgumentException is thrown by the SqliteConnection(TursoConnection, bool) constructor when the supplied TursoConnection is a local database connection. Only direct remote and embedded replica Turso connections expose the managed backend that the wrapper relies on.

Source

Thrown at bindings/dotnet/src/Turso.Data.Sqlite/SqliteConnection.cs:50

    private bool _extensionsEnabled;
    private readonly List<(string File, string? Proc)> _pendingExtensions = [];

    public SqliteConnection()
    {
    }

    public SqliteConnection(string? connectionString)
    {
        ConnectionString = connectionString;
    }

    public SqliteConnection(TursoConnection connection, bool ownsConnection)
    {
        ArgumentNullException.ThrowIfNull(connection);
        var options = new SqliteConnectionStringBuilder(connection.ConnectionString);
        if (options.IsLocal)
        {
            throw new ArgumentException(
                "Only direct remote and embedded replica Turso connections can be wrapped.",
                nameof(connection));
        }

        _connectionOptions = options;
        _managedConnection = connection;
        _ownsManagedConnection = ownsConnection;
        _wrapsManagedConnection = true;
        _readOnly = options.Mode == SqliteOpenMode.ReadOnly;
    }

    [AllowNull]
    public override string ConnectionString
    {
        get => _connectionOptions.ConnectionString;
        set
        {
            if (State == ConnectionState.Open)

View on GitHub (pinned to 6c72522679)

Solutions

1. Wrap only TursoConnection instances opened as direct remote or embedded replica connections
2. For local databases, use the regular SqliteConnection(connectionString) native path instead of the TursoConnection wrapper
3. Check the TursoConnection.ConnectionString with SqliteConnectionStringBuilder and verify IsLocal is false before constructing the wrapper

Example fix

// before
var turso = new TursoConnection("file:local.db");
var wrapper = new SqliteConnection(turso, ownsConnection: true); // throws

// after
var turso = new TursoConnection("libsql://my-db.turso.io");
var wrapper = new SqliteConnection(turso, ownsConnection: true);

if (new SqliteConnectionStringBuilder(tursoConn.ConnectionString).IsLocal)
    return new SqliteConnection(tursoConn.ConnectionString); // native path instead

bool Wrappable(TursoConnection c) => !new SqliteConnectionStringBuilder(c.ConnectionString).IsLocal;

try { return new SqliteConnection(tursoConn, true); }
catch (ArgumentException ex) when (ex.Message.Contains("embedded replica"))
{
    return new SqliteConnection(tursoConn.ConnectionString);
}

When it happens

Trigger: Calling new SqliteConnection(tursoConnection, ownsConnection: true) where tursoConnection's connection string resolves to a local file (options.IsLocal is true), e.g. a connection opened with a plain file path.

Common situations: Mixing up local and remote TursoConnection objects when refactoring code from the native SQLite path to the managed facade; dynamically choosing connection targets and passing a local one to the wrapper by mistake.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Offset and count were out of bounds for the array.
• invalid config: url is required
• Connection must be a TursoConnection.
• Connection must be set before executing a command.
• Connection must be set before preparing a command.

AI-assisted analysis of tursodatabase/turso@6c72522679 (2026-09-06). Data as JSON: /api/errors/42990b670cfe5416. Report an issue: GitHub.