tursodatabase/turso · error · InvalidOperationException

Remote Turso URLs must not include query strings or fragment

Error message

Remote Turso URLs must not include query strings or fragments.

What it means

GetRemoteUri() rejects remote Turso URLs that contain a query string ('?...') or a fragment ('#...'). The remote pipeline authenticates via the Authorization header and normalizes the URL through UriBuilder, so it has no way to carry extra URL components; their presence almost always means config written for a different libsql client. The token belongs in the 'Auth Token' connection keyword, not in the URL.

Source

Thrown at bindings/dotnet/src/Turso.Data/TursoConnectionOptions.cs:134

        {
            throw new InvalidOperationException(
                "Remote Encryption Cipher and Remote Encryption Key must be specified together.");
        }

        return new TursoRemoteEncryptionOptions
        {
            Cipher = TursoRemoteEncryptionOptions.ParseCipher(cipher),
            Key = key,
        };
    }

    public Uri GetRemoteUri()
    {
        if (!Uri.TryCreate(DataSource, UriKind.Absolute, out var uri) || !IsRemoteScheme(uri.Scheme))
            throw new InvalidOperationException($"Data Source is not a remote Turso URL: {DataSource}");

        if (!string.IsNullOrEmpty(uri.Query) || !string.IsNullOrEmpty(uri.Fragment))
            throw new InvalidOperationException("Remote Turso URLs must not include query strings or fragments.");
        if (!string.IsNullOrEmpty(uri.UserInfo))
            throw new InvalidOperationException("Remote Turso URLs must not include embedded user information; use Auth Token instead.");
        if (string.IsNullOrEmpty(uri.Host))
            throw new InvalidOperationException("Remote Turso URLs must include a host.");

        var scheme = uri.Scheme.ToLowerInvariant() switch
        {
            "libsql" => Tls == false ? "http" : "https",
            "turso" => ValidateTls(uri.Scheme, expectedTls: true, normalizedScheme: "https"),
            "http" => ValidateTls(uri.Scheme, expectedTls: false),
            "https" => ValidateTls(uri.Scheme, expectedTls: true),
            "ws" => ValidateTls(uri.Scheme, expectedTls: false, normalizedScheme: "http"),
            "wss" => ValidateTls(uri.Scheme, expectedTls: true, normalizedScheme: "https"),
            _ => throw new InvalidOperationException($"Unsupported remote Turso URL scheme: {uri.Scheme}")
        };

        var builder = new UriBuilder(uri)
        {

View on GitHub (pinned to 6c72522679)

Solutions

1. Remove the query string and fragment so the URL is bare scheme://host/path.
2. Move the auth token into the connection string: 'Auth Token=eyJ...' (or 'DataSource=...;AuthToken=...').
3. If you copied the URL from another libsql SDK, re-check which parts of it are meant to be connection keywords instead.

Example fix

// before
Data Source=libsql://db.turso.io?auth=eyJhbGciOiJ...;

// after
Data Source=libsql://db.turso.io;Auth Token=eyJhbGciOiJ...;

var raw = config["Turso:Url"]!;
var sanitized = raw.Split('?', '#')[0]; // strip query/fragment before building the connection string
var cs = $"Data Source={sanitized};Auth Token={config["Turso:Token"]}";

try { await conn.OpenAsync(ct); } catch (InvalidOperationException ex) when (ex.Message.Contains("query strings or fragments")) { /* log that the URL carried a query/fragment; point to Auth Token keyword */ }

When it happens

Trigger: Opening a connection whose Data Source is e.g. 'libsql://db.turso.io?auth=eyJhbGci...' or 'https://db.turso.io/mydb#section' — any absolute libsql/http/https/ws/wss URL with a non-empty Uri.Query or Uri.Fragment triggers the exception.

Common situations: Copying a URL from the libsql TypeScript or Python clients, which accept the auth token as a '?auth=' query parameter; pasting a dashboard URL that carries a '#fragment'; appending instance or cache-busting parameters to the database URL.

Related errors

• Data Source is not a remote Turso URL: {DataSource}
• Remote Turso URLs must not include embedded user information
• Remote Turso URLs must include a host.
• Unsupported remote Turso URL scheme: {uri.Scheme}
• Embedded replica connections are not supported yet by the .N

AI-assisted analysis of tursodatabase/turso@6c72522679 (2026-08-20). Data as JSON: /api/errors/b0239b0cd918ae31. Report an issue: GitHub.