tursodatabase/turso · error · InvalidOperationException

Partial sync requires BootstrapIfEmpty=True.

Error message

Partial sync requires BootstrapIfEmpty=True.

What it means

Validate requires that when PartialSync is configured, BootstrapIfEmpty is true. Partial sync bootstraps a fresh local replica by pulling only the specified prefix/query, which inherently depends on the bootstrap-if-empty flow; disabling it while requesting partial sync is contradictory and rejected.

Source

Thrown at bindings/dotnet/src/Turso.Data/TursoSyncDatabaseOptions.cs:181

            throw new InvalidOperationException(
                "Auth Token requires an HTTPS sync URL unless the host is localhost or loopback.");
        }

        if (LongPollTimeout is { } timeout
            && (timeout < TimeSpan.FromMilliseconds(1) || timeout.TotalMilliseconds > int.MaxValue))
        {
            throw new ArgumentOutOfRangeException(
                nameof(LongPollTimeout),
                timeout,
                $"Long-poll timeout must be between 1 and {int.MaxValue} milliseconds.");
        }

        ValidateNativeSize(PushOperationsThreshold, nameof(PushOperationsThreshold));
        ValidateNativeSize(PullBytesThreshold, nameof(PullBytesThreshold));
        PartialSync?.Validate();

        if (PartialSync is not null && !BootstrapIfEmpty)
            throw new InvalidOperationException("Partial sync requires BootstrapIfEmpty=True.");
        if (PartialSync is not null && RemoteEncryption is not null)
            throw new InvalidOperationException("Partial sync cannot be combined with remote encryption.");
        if (PartialSync?.Query is not null && PullBytesThreshold.HasValue)
        {
            throw new InvalidOperationException(
                "PullBytesThreshold cannot be combined with query partial bootstrap.");
        }
        if (PartialSync is not null && OperatingSystem.IsWindows())
        {
            throw new PlatformNotSupportedException(
                "Partial sync on Windows requires native sparse-file hole detection that is not yet implemented.");
        }

        RemoteEncryption?.Validate();
    }

    private static void ValidateNativeSize(long? value, string parameterName)
    {

View on GitHub (pinned to c1e5928725)

Solutions

1. Remove BootstrapIfEmpty = false (default is true) when using PartialSync.
2. If bootstrap must stay off, remove the PartialSync option and use a full sync instead.

Example fix

// before
var opts = new TursoSyncDatabaseOptions(path, uri) { BootstrapIfEmpty = false, PartialSync = new() { PrefixLength = 100 } };
// after
var opts = new TursoSyncDatabaseOptions(path, uri) { PartialSync = new() { PrefixLength = 100 } };

static void EnsurePartialSyncBootstrap(bool? bootstrapIfEmpty, object? partialSync)
{
    if (partialSync is not null && bootstrapIfEmpty == false)
        throw new InvalidOperationException("PartialSync requires BootstrapIfEmpty=true.");
}

static bool PartialSyncConfigIsValid(bool bootstrapIfEmpty, object? partialSync) => partialSync is null || bootstrapIfEmpty;

try { var db = new TursoSyncDatabase(opts); }
catch (InvalidOperationException ex) when (ex.Message.Contains("BootstrapIfEmpty"))
{
    // drop BootstrapIfEmpty=false or drop PartialSync, then retry
}

When it happens

Trigger: Constructing TursoSyncDatabaseOptions with PartialSync = new TursoPartialSyncOptions { ... } and BootstrapIfEmpty = false — TursoSyncDatabaseOptions.cs:180-181.

Common situations: Turning off BootstrapIfEmpty to avoid touching an existing local file while separately enabling partial sync, partial-sync snippets copied into configs that already disabled bootstrap.

Related errors

• Partial sync cannot be combined with remote encryption.
• PullBytesThreshold cannot be combined with query partial boo
• Partial sync on Windows requires native sparse-file hole det
• Automatic sync is not supported for embedded replica connect
• Turso sync operations cannot be reentered from the sync HTTP

AI-assisted analysis of tursodatabase/turso@c1e5928725 (2026-08-31). Data as JSON: /api/errors/4d63ef3a9af07b13. Report an issue: GitHub.