tursodatabase/turso · error · ArgumentOutOfRangeException

Long-poll timeout must be between 1 and {int.MaxValue} milli

Error message

Long-poll timeout must be between 1 and {int.MaxValue} milliseconds.

What it means

Validate bounds LongPollTimeout to between 1 millisecond and int.MaxValue milliseconds (~24.8 days). The value is forwarded to native code as an integer millisecond count, so zero/negative values and TimeSpan values larger than int.MaxValue ms cannot be represented and are rejected with ArgumentOutOfRangeException.

Source

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

    internal void Validate()
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(Path);
        ArgumentException.ThrowIfNullOrWhiteSpace(ClientName);

        var normalizedUri = GetNormalizedRemoteUri();
        if (!string.IsNullOrWhiteSpace(AuthToken)
            && normalizedUri.Scheme != Uri.UriSchemeHttps
            && !normalizedUri.IsLoopback)
        {
            throw new InvalidOperationException(
                "Auth Token requires an HTTPS sync URL unless the host is localhost or loopback.");
        }

        if (LongPollTimeout is { } timeout
            && (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.");
        }

View on GitHub (pinned to c1e5928725)

Solutions

1. Clamp LongPollTimeout to TimeSpan.FromMilliseconds(1)..TimeSpan.FromMilliseconds(int.MaxValue).
2. If you intended no limit, set LongPollTimeout to null instead of a huge TimeSpan.
3. Use a sane value like TimeSpan.FromSeconds(30) unless you have a specific long-poll requirement.

Example fix

// before
LongPollTimeout = TimeSpan.FromDays(30)
// after
LongPollTimeout = TimeSpan.FromSeconds(30)

static TimeSpan? EnsureValidLongPollTimeout(TimeSpan? t) => t switch
{
    null => null,
    var v when v < TimeSpan.FromMilliseconds(1) => throw new ArgumentOutOfRangeException(nameof(t), "Must be >= 1ms"),
    var v when v.TotalMilliseconds > int.MaxValue => throw new ArgumentOutOfRangeException(nameof(t), "Must be <= int.MaxValue ms (~24.8 days)"),
    _ => t
};

static bool IsValidLongPollTimeout(TimeSpan? t) => t is null || (t >= TimeSpan.FromMilliseconds(1) && t.Value.TotalMilliseconds <= int.MaxValue);

try { var db = new TursoSyncDatabase(opts); }
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == nameof(TursoSyncDatabaseOptions.LongPollTimeout))
{
    // clamp the value and retry
}

When it happens

Trigger: Setting LongPollTimeout to TimeSpan.Zero, a negative TimeSpan, or a value exceeding ~24.8 days (e.g. TimeSpan.FromDays(30)) when constructing TursoSyncDatabaseOptions — TursoSyncDatabaseOptions.cs:167-174.

Common situations: Using TimeSpan.MaxValue or Timeout constants meant for 'infinite', specifying days when the limit is ~24 days, copy-pasting a 0 timeout to disable long-polling.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Automatic sync is not supported for embedded replica connect
• Turso sync operations cannot be reentered from the sync HTTP
• The sync remote URL must not include a query string or fragm
• Use AuthToken instead of embedding credentials in the sync U
• The sync remote URL must include a host.

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