tursodatabase/turso · error · PlatformNotSupportedException

Partial sync on Windows requires native sparse-file hole det

Error message

Partial sync on Windows requires native sparse-file hole detection that is not yet implemented.

What it means

Validate refuses PartialSync on Windows. Partial sync creates sparse files with holes for unpulled segments and relies on native sparse-file hole detection that is not implemented on Windows, so the feature is explicitly unsupported there and throws PlatformNotSupportedException.

Source

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

                $"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)
            throw new ArgumentOutOfRangeException(parameterName, value, "The value exceeds the native platform size.");
    }
}

public sealed record TursoSyncStats(

View on GitHub (pinned to c1e5928725)

Solutions

1. Run the sync workload on Linux or macOS, or move it to a Linux container.
2. Remove PartialSync on Windows and use full sync (default) instead.
3. Branch configuration at startup on OperatingSystem.IsWindows() so Windows deployments fall back to full sync.

Example fix

// before
var opts = new TursoSyncDatabaseOptions(path, uri) { PartialSync = new() { PrefixLength = 100 } };
// after
var opts = OperatingSystem.IsWindows()
    ? new TursoSyncDatabaseOptions(path, uri)
    : new TursoSyncDatabaseOptions(path, uri) { PartialSync = new() { PrefixLength = 100 } };

static bool PartialSyncSupportedOnThisOs() => !OperatingSystem.IsWindows();
// at config time:
var partialSync = OperatingSystem.IsWindows() ? null : new TursoPartialSyncOptions { PrefixLength = 100 };

static bool CanUsePartialSync() => !OperatingSystem.IsWindows();

try { var db = new TursoSyncDatabase(opts); }
catch (PlatformNotSupportedException ex) when (ex.Message.Contains("Partial sync on Windows"))
{
    // rebuild options without PartialSync and retry
}

When it happens

Trigger: Constructing TursoSyncDatabase with PartialSync set while running on any Windows platform (OperatingSystem.IsWindows() true at TursoSyncDatabaseOptions.cs:189-193).

Common situations: Deploying a partial-sync-based .NET service to Windows containers or Windows Server, developing on a Windows workstation with a config copied from a Linux colleague, CI matrix running the same sync code on windows-latest runners.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

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