tursodatabase/turso · error · ArgumentOutOfRangeException

Segment size exceeds the native platform size.

Error message

Segment size exceeds the native platform size.

What it means

SegmentSize is ultimately passed to native code as a platform-sized integer (nuint). If the supplied value exceeds nuint.MaxValue on the current platform (notably > uint.MaxValue on 32-bit runtimes), Validate throws ArgumentOutOfRangeException because the value cannot be represented natively.

Source

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

    public string? Query { get; init; }
    public long? SegmentSize { get; init; }
    public bool Prefetch { get; init; }

    internal void Validate()
    {
        if (Query is not null)
            ArgumentException.ThrowIfNullOrWhiteSpace(Query);

        var hasPrefix = PrefixLength.HasValue;
        var hasQuery = Query is not null;
        if (hasPrefix == hasQuery)
            throw new InvalidOperationException("Partial sync requires exactly one prefix or query bootstrap strategy.");
        if (PrefixLength is <= 0)
            throw new ArgumentOutOfRangeException(nameof(PrefixLength), PrefixLength, "Prefix length must be positive.");
        if (SegmentSize is <= 0)
            throw new ArgumentOutOfRangeException(nameof(SegmentSize), SegmentSize, "Segment size must be positive.");
        if (SegmentSize is { } segmentSize && (ulong)segmentSize > nuint.MaxValue)
            throw new ArgumentOutOfRangeException(nameof(SegmentSize), SegmentSize, "Segment size exceeds the native platform size.");
    }
}

public sealed class TursoSyncDatabaseOptions
{
    public TursoSyncDatabaseOptions(string path, Uri remoteUri)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(path);
        ArgumentNullException.ThrowIfNull(remoteUri);
        Path = path;
        RemoteUri = remoteUri;
    }

    public string Path { get; }
    public Uri RemoteUri { get; }
    public string? AuthToken { get; init; }
    public string ClientName { get; init; } = "turso-sync-dotnet";
    public TimeSpan? LongPollTimeout { get; init; }

View on GitHub (pinned to c1e5928725)

Solutions

1. Use a realistic segment size (e.g. megabytes range) instead of a max-value sentinel
2. Leave SegmentSize null to let the library choose a platform-appropriate default
3. On 32-bit targets, keep the value <= uint.MaxValue; prefer explicit values like 1MB–64MB

Example fix

// before
var partial = new TursoPartialSyncOptions { PrefixLength = 4096, SegmentSize = long.MaxValue };
// after
var partial = new TursoPartialSyncOptions { PrefixLength = 4096, SegmentSize = 8 * 1024 * 1024 };

// before constructing options:
if (segmentSize is > 0 && (ulong)segmentSize > (ulong)nuint.MaxValue)
    throw new ArgumentOutOfRangeException(nameof(segmentSize), segmentSize, "Segment size exceeds the native platform size.");

try
{
    var db = new TursoSyncDatabase(options);
}
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "SegmentSize")
{
    logger.LogError(ex, "SegmentSize is too large for this platform ({Bits}-bit).", Environment.Is64BitProcess ? 64 : 32);
    throw;
}

When it happens

Trigger: Setting SegmentSize to a very large value (e.g. long.MaxValue or ulong.MaxValue, or > 4294967295 on a 32-bit process) while running under a 32-bit runtime.

Common situations: Using int.MaxValue/long.MaxValue as a 'unlimited' sentinel on 32-bit deployments (e.g. some mobile/IoT targets); hard-coded huge values copied from 64-bit examples.

Related errors

• Prefix length must be positive.
• Segment size must be positive.
• Partial sync requires exactly one prefix or query bootstrap
• The sync remote URL must be absolute.
• Auth Token requires a remote Turso URL Data Source.

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