tursodatabase/turso · error · InvalidOperationException

Tls requires a remote Turso URL Data Source.

Error message

Tls requires a remote Turso URL Data Source.

What it means

ValidateLocalOnlyOptions rejects an explicit 'Tls' value on local connections: Tls controls the transport scheme for remote URLs (for example libsql:// maps to https unless Tls=false). A local file database has no transport, so Open() throws 'Tls requires a remote Turso URL Data Source.'

Source

Thrown at bindings/dotnet/src/Turso.Data/TursoConnection.cs:343

        if (_connectionOptions.SyncInterval > 0)
            throw new NotSupportedException("Sync Interval requires embedded replica support, which is not supported yet by the .NET provider.");

        if (_connectionOptions.GetEncryptionCipher().HasValue || !string.IsNullOrWhiteSpace(_connectionOptions["Encryption Key"]))
            throw new InvalidOperationException("Encryption Cipher and Encryption Key are local database options and cannot be used with remote Turso URLs.");

        _remoteClient = new TursoRemoteClient(_connectionOptions.GetRemoteUri(), _connectionOptions.AuthToken);
    }

    private void ValidateLocalOnlyOptions()
    {
        if (!string.IsNullOrWhiteSpace(_connectionOptions.AuthToken))
            throw new InvalidOperationException("Auth Token requires a remote Turso URL Data Source.");
        if (!string.IsNullOrWhiteSpace(_connectionOptions.ReplicaPath))
            throw new InvalidOperationException("Replica Path requires a remote Turso URL Data Source.");
        if (_connectionOptions.SyncInterval > 0)
            throw new InvalidOperationException("Sync Interval requires a remote embedded replica connection.");
        if (_connectionOptions.Tls.HasValue)
            throw new InvalidOperationException("Tls requires a remote Turso URL Data Source.");
    }

    private void CloseRemote()
    {
        var remoteClient = _remoteClient;
        if (remoteClient is null)
            return;

        Exception? closeError = null;
        try
        {
            if (_remoteTransactionActive)
            {
                remoteClient
                    .ExecuteAsync("ROLLBACK", new TursoParameterCollection(), wantRows: false, DefaultTimeout, closeAfter: true, CancellationToken.None)
                    .GetAwaiter()
                    .GetResult();
            }

View on GitHub (pinned to 244cde92a7)

Solutions

1. Remove the 'Tls' keyword for local file databases
2. For remote URLs keep or adjust it: 'Tls=false' with libsql/http downgrades to plaintext HTTP
3. Clean mode-specific keywords whenever the Data Source mode changes

Example fix

// before
var cs = "Data Source=app.db;Tls=true";

// after
var cs = "Data Source=app.db";
// remote equivalent: "Data Source=libsql://db.turso.io;Tls=true"

var opts = TursoConnectionOptions.Parse(cs);
if (!opts.IsRemote && opts.Tls.HasValue)
    throw new InvalidOperationException(
        "Remove 'Tls' or switch Data Source to a remote URL.");

static bool TlsMatchesMode(string cs)
{
    var opts = TursoConnectionOptions.Parse(cs);
    return opts.IsRemote || !opts.Tls.HasValue;
}

try { conn.Open(); }
catch (InvalidOperationException ex) when (ex.Message == "Tls requires a remote Turso URL Data Source.")
{
    // remove 'Tls' for local databases; keep it only on remote URLs
}

When it happens

Trigger: Open() with 'Data Source=app.db;Tls=true' (or false); a Tls keyword left behind after changing the Data Source from a URL to a local file; config templates that pin TLS settings on every connection.

Common situations: Security baselines that force 'Tls=true' on all database connections; switching between remote and local modes by editing only Data Source; copied connection strings from HTTP-tunnelled remote setups.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Auth Token requires a remote Turso URL Data Source.
• Replica Path requires a remote Turso URL Data Source.
• Sync Interval requires a remote embedded replica connection.
• Keyword not supported: {keyword}.
• Embedded replica connections are not supported yet by the .N

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/db27d72d7e98a787. Report an issue: GitHub.