tursodatabase/turso · error · InvalidOperationException

Encryption Key is required when Encryption Cipher is specifi

Error message

Encryption Key is required when Encryption Cipher is specified.

What it means

For local (non-URL) databases, Open() reads Encryption Cipher and Encryption Key from the connection string (TursoConnection.cs:70-78). A cipher without a key is rejected with InvalidOperationException because TursoBindings.OpenDatabaseWithEncryption needs the hex-encoded key material to open the encrypted database file.

Source

Thrown at bindings/dotnet/src/Turso.Data/TursoConnection.cs:93

        if (_turso is not null || _remoteClient is not null)
            throw new InvalidOperationException("The connection is already open.");

        if (_connectionOptions.IsRemote)
        {
            OpenRemote();
            return;
        }

        ValidateLocalOnlyOptions();

        var filename = _connectionOptions["Data Source"] ?? ":memory:";
        var cipher = _connectionOptions.GetEncryptionCipher();
        var hexkey = _connectionOptions["Encryption Key"];

        if (cipher.HasValue)
        {
            if (string.IsNullOrWhiteSpace(hexkey))
                throw new InvalidOperationException("Encryption Key is required when Encryption Cipher is specified.");

            _turso = TursoBindings.OpenDatabaseWithEncryption(filename, cipher.Value, hexkey);
        }
        else
        {
            _turso = TursoBindings.OpenDatabase(filename);
        }
    }

    public override Task OpenAsync(CancellationToken cancellationToken)
    {
        if (cancellationToken.IsCancellationRequested)
            return Task.FromCanceled(cancellationToken);

        if (_connectionOptions.IsReplica)
            return OpenReplicaAsync(cancellationToken);

        Open();

View on GitHub (pinned to 6c72522679)

Solutions

Add the hex key: "Data Source=file.db;Encryption Cipher=Aes256;Encryption Key=<hex>".
Compose the connection string at runtime, injecting the key from your secret store (env var / key vault) rather than hardcoding it.
If encryption is not intended, remove the Encryption Cipher option entirely so the plain OpenDatabase path is used.

Example fix

// before
var cs = "Data Source=app.db;Encryption Cipher=Aes256"; // no key -> throws on Open

// after
var cs = $"Data Source=app.db;Encryption Cipher=Aes256;Encryption Key={Environment.GetEnvironmentVariable("TURSO_HEX_KEY")}";

Defensive patterns

Strategy: validation

Validate before calling

var opts = TursoConnectionOptions.Parse(cs);
var cipher = opts.GetEncryptionCipher();
var key = opts["Encryption Key"];
if (cipher.HasValue && string.IsNullOrWhiteSpace(key))
    throw new InvalidOperationException("Encryption Key missing for encrypted local database.");

Prevention

Compose the connection string at runtime and inject the key from a secret store.
Validate cipher/key pairing in startup checks before any connection is opened.
Name the key consistently (e.g. TURSO_HEX_KEY) across environments.

When it happens

Trigger: Connection string "Data Source=file.db;Encryption Cipher=Aes256" with no Encryption Key entry (or a whitespace one), on a local/embedded database.

Common situations: The key lives in a secret store/env var and was never merged into the connection string; connection-string transforms scrubbed the key for security; the cipher option was copied from docs while the key line was dropped.

Related errors

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