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.

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";
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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
}

Prevention

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

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

Appendix: source

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

            if (!ReferenceEquals(sender, _automaticSyncCoordinator))
                return;

            Volatile.Write(ref _automaticSyncStatus, args.Status);
            generation = Volatile.Read(ref _automaticSyncGeneration);
            handlers = AutomaticSyncStatusChanged;
        }

        QueueAutomaticSyncStatusChanged(handlers, args.Status, generation);
    }

    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.HasAdvancedReplicaOptions)
            throw new InvalidOperationException("Advanced sync options require 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)
            {
                if (_remoteTransactionFailure is null)

View on GitHub (pinned to 6c72522679)