tursodatabase/turso · error · ArgumentOutOfRangeException

Prefix length must be positive.

Error message

Prefix length must be positive.

What it means

When Validate processes a prefix bootstrap (PrefixLength is set), it requires a strictly positive value via ArgumentOutOfRangeException. A PrefixLength of zero or negative is meaningless as a bootstrap size and is rejected.

Source

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

public sealed class TursoPartialSyncOptions
{
    public int? PrefixLength { get; init; }
    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; }

View on GitHub (pinned to c1e5928725)

Solutions

1. Set PrefixLength to a positive value greater than 0
2. If you don't know a good size, drop PrefixLength and use a Query bootstrap instead
3. Guard the computed value before constructing options (Math.Max(1, computedSize))

Example fix

// before
var partial = new TursoPartialSyncOptions { PrefixLength = 0 };
// after
var partial = new TursoPartialSyncOptions { PrefixLength = 4096 };

// before constructing options:
if (prefixLength is <= 0)
    throw new ArgumentOutOfRangeException(nameof(prefixLength), prefixLength, "Prefix length must be positive.");

try
{
    var db = new TursoSyncDatabase(options);
}
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "PrefixLength")
{
    logger.LogError(ex, "Partial sync PrefixLength must be a positive number.");
    throw;
}

When it happens

Trigger: Creating TursoPartialSyncOptions with PrefixLength = 0 or a negative value while Query is null (so the prefix strategy is selected).

Common situations: Computing the prefix size from a variable that defaults to 0; int/long underflow; config files with an empty value coerced to 0.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Segment size must be positive.
• Segment size exceeds the native platform size.
• 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/310b6900a5292e4a. Report an issue: GitHub.