tursodatabase/turso · error · ArgumentException

Unsupported keyword: {keyword}

Error message

Unsupported keyword: {keyword}

What it means

TursoConnectionStringBuilder.NormalizeKeyword() throws this ArgumentException for any connection-string keyword not in its KeywordMap. The builder is a closed keyword set: only Data Source (DataSource/Filename), Mode, Cache, Password, Foreign Keys, Recursive Triggers, Default Timeout (Command Timeout), Pooling, Vfs, Encryption Cipher, Encryption Key, Auth Token (Authentication Token), Replica Path, Read Your Writes, Sync Interval, and Tls are accepted (each with and without spaces). Unknown keys are rejected rather than ignored so typos fail fast.

Source

Thrown at bindings/dotnet/src/Turso.Data/TursoConnectionStringBuilder.cs:347

        {
            "aes128gcm" => TursoEncryptionCipher.Aes128Gcm,
            "aes256gcm" => TursoEncryptionCipher.Aes256Gcm,
            "aegis256" => TursoEncryptionCipher.Aegis256,
            "aegis256x2" => TursoEncryptionCipher.Aegis256x2,
            "aegis128l" => TursoEncryptionCipher.Aegis128l,
            "aegis128x2" => TursoEncryptionCipher.Aegis128x2,
            "aegis128x4" => TursoEncryptionCipher.Aegis128x4,
            _ => throw new InvalidOperationException($"Unknown encryption cipher: {cipher}")
        };
    }

    private static string NormalizeKeyword(string keyword)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(keyword);
        if (KeywordMap.TryGetValue(keyword, out var normalizedKeyword))
            return normalizedKeyword;

        throw new ArgumentException($"Unsupported keyword: {keyword}", nameof(keyword));
    }

    private string GetString(string keyword) => GetOption(keyword) ?? string.Empty;

    private void SetString(string keyword, string value)
    {
        ArgumentNullException.ThrowIfNull(value);
        this[keyword] = value;
    }

    private bool GetBool(string keyword, bool defaultValue = false)
    {
        return TryGetValue(keyword, out var value)
            ? Convert.ToBoolean(value, CultureInfo.InvariantCulture)
            : defaultValue;
    }

    private bool? GetNullableBool(string keyword)

View on GitHub (pinned to c1e5928725)

Solutions

1. Map foreign keys to the Turso equivalents: Server/Host -> Data Source, token/password -> Auth Token or Password, timeout -> Default Timeout.
2. Remove keys the provider does not support instead of leaving them commented-in.
3. Check spelling and spacing variants against the accepted list (e.g. 'Datasource' is invalid; 'DataSource' and 'Data Source' both work).

Example fix

// before
var cs = "Server=db.example.com;Database=app;User Id=sa;Password=pw;Timeout=30";

// after
var cs = "Data Source=libsql://db.example.com;Auth Token=pw;Default Timeout=30";

var b = new TursoConnectionStringBuilder();
foreach (var key in incomingKeys)
    if (!b.ContainsKey(key)) // throws on unknown; use a whitelist check first instead
        { }
// safer: validate against your own allowed-key list before assigning ConnectionString

try { builder.ConnectionString = cs; } catch (ArgumentException ex) when (ex.Message.StartsWith("Unsupported keyword")) { /* extract keyword, report which key is invalid to config owner */ }

When it happens

Trigger: Assigning ConnectionString or the indexer with keys like 'Server=', 'Database=', 'User ID=', 'Version=', 'Journal Mode=', 'Max Pool Size=', or misspelling a valid key ('Datasource=', 'AuthTokem='). DbConnectionStringBuilder normally tolerates unknown keys, but this override validates every key through NormalizeKeyword on get, set, ContainsKey, Remove, and TryGetValue.

Common situations: Porting a connection string from SQL Server/Npgsql/MySQL ('Server=;Database=;User Id=;Password=' style); copying Microsoft.Data.Sqlite options that this builder never implemented ('Journal Mode', 'Busy Timeout', 'Default Timeout' exists but 'Busy Timeout' does not); CI secrets injecting extra keys into the connection string.

Related errors

• Embedded replica connections are not supported yet by the .N
• Sync Interval requires embedded replica support, which is no
• Auth Token requires a remote Turso URL Data Source.
• Unknown encryption cipher: {cipher}
• Data Source is not a remote Turso URL: {DataSource}

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