tursodatabase/turso · error · InvalidOperationException

Auth Token requires a remote Turso URL Data Source.

Error message

Auth Token requires a remote Turso URL Data Source.

What it means

Before opening a local (non-URL) database, Open() runs ValidateLocalOnlyOptions, which rejects keywords that only make sense remotely. The first check throws 'Auth Token requires a remote Turso URL Data Source.' when a non-whitespace Auth Token is present: tokens authenticate to a Turso server, so pairing one with a file path is contradictory.

Source

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

    private void OpenRemote()
    {
        if (_connectionOptions.IsReplica)
            throw new NotSupportedException("Embedded replica connections are not supported yet by the .NET provider. Use a remote URL without Replica Path for direct remote execution.");

        if (_connectionOptions.SyncInterval > 0)
            throw new NotSupportedException("Sync Interval requires embedded replica support, which is not supported yet by the .NET provider.");

        if (_connectionOptions.GetEncryptionCipher().HasValue || !string.IsNullOrWhiteSpace(_connectionOptions["Encryption Key"]))
            throw new InvalidOperationException("Encryption Cipher and Encryption Key are local database options and cannot be used with remote Turso URLs.");

        _remoteClient = new TursoRemoteClient(_connectionOptions.GetRemoteUri(), _connectionOptions.AuthToken);
    }

    private void ValidateLocalOnlyOptions()
    {
        if (!string.IsNullOrWhiteSpace(_connectionOptions.AuthToken))
            throw new InvalidOperationException("Auth Token requires a remote Turso URL Data Source.");
        if (!string.IsNullOrWhiteSpace(_connectionOptions.ReplicaPath))
            throw new InvalidOperationException("Replica Path requires a remote Turso URL Data Source.");
        if (_connectionOptions.SyncInterval > 0)
            throw new InvalidOperationException("Sync Interval requires a remote embedded replica connection.");
        if (_connectionOptions.Tls.HasValue)
            throw new InvalidOperationException("Tls requires a remote Turso URL Data Source.");
    }

    private void CloseRemote()
    {
        var remoteClient = _remoteClient;
        if (remoteClient is null)
            return;

        Exception? closeError = null;
        try
        {
            if (_remoteTransactionActive)

View on GitHub (pinned to 244cde92a7)

Solutions

1. Remove 'Auth Token' for local file databases
2. Or switch Data Source to a remote URL (libsql:// or https://) where the token is required and used
3. Keep local and remote connection strings in separate config files (appsettings.Local.json vs appsettings.json)

Example fix

// before
var cs = "Data Source=app.db;Auth Token=eyJhbGci..."; // local file + token

// after (local)
var cs = "Data Source=app.db";
// after (remote)
var cs = "Data Source=libsql://db.turso.io;Auth Token=eyJhbGci...";

var opts = TursoConnectionOptions.Parse(cs);
if (!opts.IsRemote && !string.IsNullOrWhiteSpace(opts.AuthToken))
    throw new InvalidOperationException(
        "Remove 'Auth Token' or switch Data Source to a libsql/https URL.");

static bool AuthTokenMatchesMode(string cs)
{
    var opts = TursoConnectionOptions.Parse(cs);
    return opts.IsRemote || string.IsNullOrWhiteSpace(opts.AuthToken);
}

try { conn.Open(); }
catch (InvalidOperationException ex) when (ex.Message == "Auth Token requires a remote Turso URL Data Source.")
{
    // drop the token for local dev, or point Data Source at the remote URL
}

When it happens

Trigger: Open() with 'Data Source=app.db;Auth Token=eyJ...' — a local file plus a token; a token injected as a default into every connection string by configuration or a secrets layer; switching a Data Source from a URL to a local file without removing the token.

Common situations: Local development inheriting cloud credentials from shared config; TURSO_AUTH_TOKEN-style env defaults applied uniformly; copy-paste from cloud connection examples.

Related errors

• Replica Path requires a remote Turso URL Data Source.
• Sync Interval requires a remote embedded replica connection.
• Tls requires a remote Turso URL Data Source.
• Keyword not supported: {keyword}.
• Embedded replica connections are not supported yet by the .N

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/04dcccdd917d3e1b. Report an issue: GitHub.