tursodatabase/turso · error · InvalidOperationException

PullBytesThreshold cannot be combined with query partial boo

Error message

PullBytesThreshold cannot be combined with query partial bootstrap.

What it means

When PartialSync uses a Query bootstrap strategy, Validate forbids also setting PullBytesThreshold. The query bootstrap defines exactly what to pull, so a byte-threshold pull limit would conflict with it; the combination throws InvalidOperationException.

Source

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

            && (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)
    {
        if (value is null)
            return;
        if (value <= 0)
            throw new ArgumentOutOfRangeException(parameterName, value, "The value must be positive.");
        if ((ulong)value > nuint.MaxValue)

View on GitHub (pinned to c1e5928725)

Solutions

1. Remove PullBytesThreshold when PartialSync.Query is set.
2. Use PrefixLength bootstrap instead of Query if you want byte/segment-based thresholds alongside partial sync.
3. Constrain the query itself (e.g. tighter WHERE clause) instead of using a byte threshold.

Example fix

// before
var opts = new TursoSyncDatabaseOptions(path, uri)
{
    PullBytesThreshold = 1_000_000,
    PartialSync = new() { Query = "SELECT * FROM events WHERE tenant_id = 1" }
};
// after
var opts = new TursoSyncDatabaseOptions(path, uri)
{
    PartialSync = new() { Query = "SELECT * FROM events WHERE tenant_id = 1" }
};

static void EnsureQueryBootstrapHasNoByteThreshold(TursoPartialSyncOptions? partialSync, long? pullBytesThreshold)
{
    if (partialSync?.Query is not null && pullBytesThreshold.HasValue)
        throw new InvalidOperationException("Drop PullBytesThreshold when using a query bootstrap.");
}

static bool PartialThresholdComboIsValid(TursoPartialSyncOptions? ps, long? pullBytes) => ps?.Query is null || !pullBytes.HasValue;

try { var db = new TursoSyncDatabase(opts); }
catch (InvalidOperationException ex) when (ex.Message.Contains("PullBytesThreshold"))
{
    // remove PullBytesThreshold or switch to PrefixLength bootstrap
}

When it happens

Trigger: Constructing TursoSyncDatabaseOptions with PartialSync.Query set (e.g. "WHERE tenant_id = 1") and a non-null PullBytesThreshold (e.g. PullBytesThreshold = 1_000_000) — TursoSyncDatabaseOptions.cs:184-188.

Common situations: Adding a size cap to try to limit query-bootstrap pulls, merging a partial-sync config that used byte thresholds with one that uses queries.

Related errors

• Partial sync requires BootstrapIfEmpty=True.
• Partial sync cannot be combined with remote encryption.
• 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/09d1cfdca35cbbc8. Report an issue: GitHub.