tursodatabase/turso · error · ArgumentException

The sync remote URL must use turso, libsql, HTTP, or HTTPS.

Error message

The sync remote URL must use turso, libsql, HTTP, or HTTPS.

What it means

GetNormalizedRemoteUri only accepts schemes turso, libsql, http, and https; turso and libsql are normalized to https. Any other scheme (ftp, ws, file, wss, tcp, etc.) is rejected because the sync protocol runs over HTTP/HTTPS.

Source

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

    public string? ExperimentalFeatures { get; init; }

    internal Uri GetNormalizedRemoteUri()
    {
        if (!RemoteUri.IsAbsoluteUri)
            throw new ArgumentException("The sync remote URL must be absolute.", nameof(RemoteUri));
        if (!string.IsNullOrEmpty(RemoteUri.Query) || !string.IsNullOrEmpty(RemoteUri.Fragment))
            throw new ArgumentException("The sync remote URL must not include a query string or fragment.", nameof(RemoteUri));
        if (!string.IsNullOrEmpty(RemoteUri.UserInfo))
            throw new ArgumentException("Use AuthToken instead of embedding credentials in the sync URL.", nameof(RemoteUri));
        if (string.IsNullOrEmpty(RemoteUri.Host))
            throw new ArgumentException("The sync remote URL must include a host.", nameof(RemoteUri));

        var scheme = RemoteUri.Scheme.ToLowerInvariant() switch
        {
            "turso" or "libsql" => Uri.UriSchemeHttps,
            "http" => Uri.UriSchemeHttp,
            "https" => Uri.UriSchemeHttps,
            _ => throw new ArgumentException(
                "The sync remote URL must use turso, libsql, HTTP, or HTTPS.",
                nameof(RemoteUri)),
        };
        var builder = new UriBuilder(RemoteUri)
        {
            Scheme = scheme,
            Port = RemoteUri.IsDefaultPort ? -1 : RemoteUri.Port,
            UserName = string.Empty,
            Password = string.Empty,
        };
        return builder.Uri;
    }

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

View on GitHub (pinned to c1e5928725)

Solutions

1. Use https:// (or http:// for plain HTTP, or turso:// / libsql:// which map to HTTPS) as the URL scheme.
2. Convert ws/wss URLs to http/https equivalents.
3. Verify the URL string in configuration starts with an accepted scheme and has no typos.

Example fix

// before
var opts = new TursoSyncDatabaseOptions(path, new Uri("wss://mydb.turso.io"));
// after
var opts = new TursoSyncDatabaseOptions(path, new Uri("https://mydb.turso.io"));

static readonly string[] AllowedSchemes = { "turso", "libsql", "http", "https" };
static void EnsureAllowedScheme(Uri remoteUri)
{
    if (!AllowedSchemes.Contains(remoteUri.Scheme.ToLowerInvariant()))
        throw new ArgumentException($"Scheme '{remoteUri.Scheme}' not allowed; use turso, libsql, http, or https.");
}

static bool HasSyncScheme(Uri u) => u.IsAbsoluteUri && u.Scheme.ToLowerInvariant() is "turso" or "libsql" or "http" or "https";

try { var db = new TursoSyncDatabase(opts); }
catch (ArgumentException ex) when (ex.Message.Contains("must use turso, libsql, HTTP, or HTTPS"))
{
    // rewrite scheme (e.g. wss -> https) and retry
}

When it happens

Trigger: Constructing TursoSyncDatabaseOptions with a RemoteUri whose lowercase scheme is not one of turso/libsql/http/https — e.g. new Uri("wss://host/db"), "ftp://...", or a scheme typo like "htps://" (which usually fails earlier as a relative URI) — thrown at TursoSyncDatabaseOptions.cs:139-141.

Common situations: Reusing WebSocket URLs from other libsql clients (ws/wss), copying database URLs from non-Turso services, editing config and mangling the scheme, using httpx/file URIs from local-only setups.

Related errors

• The sync remote URL must not include a query string or fragm
• The sync remote URL must include a host.
• Use AuthToken instead of embedding credentials in the sync U
• 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/84d1c327687c1c47. Report an issue: GitHub.