{"record":{"id":"0a13e8f05eb61940","repo":"tursodatabase/turso","slug":"segment-size-exceeds-the-native-platform-size","errorCode":null,"errorMessage":"Segment size exceeds the native platform size.","messagePattern":"Segment size exceeds the native platform size\\.","errorType":"validation","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"bindings/dotnet/src/Turso.Data/TursoSyncDatabaseOptions.cs","lineNumber":95,"sourceCode":"    public string? Query { get; init; }\n    public long? SegmentSize { get; init; }\n    public bool Prefetch { get; init; }\n\n    internal void Validate()\n    {\n        if (Query is not null)\n            ArgumentException.ThrowIfNullOrWhiteSpace(Query);\n\n        var hasPrefix = PrefixLength.HasValue;\n        var hasQuery = Query is not null;\n        if (hasPrefix == hasQuery)\n            throw new InvalidOperationException(\"Partial sync requires exactly one prefix or query bootstrap strategy.\");\n        if (PrefixLength is <= 0)\n            throw new ArgumentOutOfRangeException(nameof(PrefixLength), PrefixLength, \"Prefix length must be positive.\");\n        if (SegmentSize is <= 0)\n            throw new ArgumentOutOfRangeException(nameof(SegmentSize), SegmentSize, \"Segment size must be positive.\");\n        if (SegmentSize is { } segmentSize && (ulong)segmentSize > nuint.MaxValue)\n            throw new ArgumentOutOfRangeException(nameof(SegmentSize), SegmentSize, \"Segment size exceeds the native platform size.\");\n    }\n}\n\npublic sealed class TursoSyncDatabaseOptions\n{\n    public TursoSyncDatabaseOptions(string path, Uri remoteUri)\n    {\n        ArgumentException.ThrowIfNullOrWhiteSpace(path);\n        ArgumentNullException.ThrowIfNull(remoteUri);\n        Path = path;\n        RemoteUri = remoteUri;\n    }\n\n    public string Path { get; }\n    public Uri RemoteUri { get; }\n    public string? AuthToken { get; init; }\n    public string ClientName { get; init; } = \"turso-sync-dotnet\";\n    public TimeSpan? LongPollTimeout { get; init; }","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/tursodatabase/turso/blob/c1e59287258d99b309e362a63f48822256e2f65f/bindings/dotnet/src/Turso.Data/TursoSyncDatabaseOptions.cs#L77-L113","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a realistic segment size (e.g. megabytes range) instead of a max-value sentinel","Leave SegmentSize null to let the library choose a platform-appropriate default","On 32-bit targets, keep the value <= uint.MaxValue; prefer explicit values like 1MB–64MB"],"exampleFix":"// before\nvar partial = new TursoPartialSyncOptions { PrefixLength = 4096, SegmentSize = long.MaxValue };\n// after\nvar partial = new TursoPartialSyncOptions { PrefixLength = 4096, SegmentSize = 8 * 1024 * 1024 };","handlingStrategy":"validation","validationCode":"// before constructing options:\nif (segmentSize is > 0 && (ulong)segmentSize > (ulong)nuint.MaxValue)\n    throw new ArgumentOutOfRangeException(nameof(segmentSize), segmentSize, \"Segment size exceeds the native platform size.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    var db = new TursoSyncDatabase(options);\n}\ncatch (ArgumentOutOfRangeException ex) when (ex.ParamName == \"SegmentSize\")\n{\n    logger.LogError(ex, \"SegmentSize is too large for this platform ({Bits}-bit).\", Environment.Is64BitProcess ? 64 : 32);\n    throw;\n}","preventionTips":["Avoid max-value sentinels (long.MaxValue) for 'unlimited'; omit the option instead","Be extra careful on 32-bit targets where the limit is uint.MaxValue","Use explicit, realistic sizes (e.g. 1MB–64MB) in configuration"],"tags":["dotnet","configuration","partial-sync","platform","argument-validation"],"backgroundTag":"value-exceeds-platform-max","analyzedSha":"c1e59287258d99b309e362a63f48822256e2f65f","analyzedAt":"2026-08-31T11:17:35.598Z","contentChangedAt":"2026-08-31T11:17:35.598Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}