tursodatabase/turso · error · InvalidOperationException

Sync Interval requires a remote embedded replica connection.

Error message

Sync Interval requires a remote embedded replica connection.

What it means

ValidateLocalOnlyOptions rejects 'Sync Interval' on local connections with 'Sync Interval requires a remote embedded replica connection.': the option schedules periodic pulls for embedded replicas, which by definition need a remote primary. A purely local file database has nothing to sync with, so Open() fails fast rather than ignoring the option.

Source

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

            throw new NotSupportedException("Embedded replica connections are not supported yet by the .NET provider. Use a remote URL without Replica Path for direct remote execution.");

        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()

View on GitHub (pinned to 244cde92a7)

Solutions

1. Remove 'Sync Interval' for local file databases
2. Note the option is currently unusable in .NET altogether: remote connections throw NotSupportedException because embedded replicas are unsupported
3. Move mode-specific keywords out of base config into per-mode config files

Example fix

// before
var cs = "Data Source=app.db;Sync Interval=10";

// after
var cs = "Data Source=app.db";

var opts = TursoConnectionOptions.Parse(cs);
if (!opts.IsRemote && opts.SyncInterval > 0)
    throw new InvalidOperationException(
        "Remove 'Sync Interval': it requires a remote embedded replica connection.");

static bool SyncIntervalMatchesMode(string cs)
{
    var opts = TursoConnectionOptions.Parse(cs);
    return opts.IsRemote || opts.SyncInterval <= 0;
}

try { conn.Open(); }
catch (InvalidOperationException ex) when (ex.Message == "Sync Interval requires a remote embedded replica connection.")
{
    // remove 'Sync Interval' from the local connection string and retry
}

When it happens

Trigger: Open() with 'Data Source=app.db;Sync Interval=10'; a sync interval left in the string after switching from a replica URL to a local file; shared config across projects where some instances are remote.

Common situations: Local development against a config written for embedded replicas; option defaults injected by tooling; misunderstanding that the option only tunes replica sync, not general refresh.

Related errors

• Replica Path requires a remote Turso URL Data Source.
• Embedded replica connections are not supported yet by the .N
• Sync Interval requires embedded replica support, which is no
• Auth Token requires a remote Turso URL Data Source.
• Tls requires a remote Turso URL Data Source.

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